Skip to main content

🛠️ Troubleshooting

This diagnostic directory provides immediate resolution paths for configuration mismatches, network timeout exceptions, dependency resolution blocks, and query structure anomalies within the ZTeraDB ecosystem.

📌 Table of Contents​

🔑 1. Configuration Diagnostics​

Mismatched or Null Credential Exception​

Exception: Missing or invalid clientKey / accessKey / secretKey

Root Cause​

The environment variables layer failed to inject system authorization objects into the execution scope during runtime initialization.

Resolution Runbook​

  1. Inspect your localized root .env configuration file for syntax completeness and proper parameter schema injection:
 ZTERADB_CONFIG={
   "clientKey": "Your ZTeraDB client key",
   "accessKey": "Your ZTeraDB access key",
   "secretKey": "Your ZTeraDB key secret",
   "databaseID": "Your ZTeraDB database id",
   "env": "Your environment of one prod/staging/qa/dev working",
   "responseDataType": "json"
 }

Configuration Payload Parsing Exception​

Exception: JSON.parse error for ZTERADB_CONFIG

Root Cause​

The structural parsing wrapper encountered a malformed or improperly escaped string representation of the JSON array within the .env context.

Resolution Runbook​

Verify your configuration block utilizing strict JSON syntax compliance checklists:

  • Ensure all keys and string properties use double quotes ("") rather than single quotes ('').
  • Remove trailing commas after the last parameter mapping block ("responseDataType": "JSON").
  • Verify balanced brace pairings wrapping the global configuration properties.

🌍 2. Network & Connection Diagnostics​

Socket Connection Refused​

Exception: Connection refused

Resolution Runbook​

  • Endpoint Validation: Confirm that the destination host and targeted application port match your infrastructure provisioning profile (Default target: "Your zteraDB server HOST":"Your zteraDB server PORT").
  • Network Isolation Policies: Verify that corporate firewall rules, local VPN tunnels, or cloud security groups allow outbound TCP handshakes over the assigned port spectrum.

Connection Reset & Timeout Interval Breach​

Exception: ECONNRESET or ETIMEDOUT

Resolution Runbook​

  1. Trigger an internal trace route or simple socket verification sequence directly from your local terminal cluster to isolate connection health: 
    telnet "Your zteraDB server HOST" "Your zteraDB server PORT"
  2. If network paths drop without returning headers, inspect system latency rates or introduce retry loops around your driver configuration instances.

📦 3. Dependency & Import Diagnostics​

Module Definition Undefined Exception​

Exception: Cannot find module '@zteradb/client'

Root Cause​

The Node package manager registry engine has an un-synchronized tracking index, or the package target is missing within the active node_modules scope.

Resolution Runbook​

  1. Force-register the package module dependencies directly inside your local execution tree:

    npm install @zteradb/client

  2. For highly persistent module tree discrepancies, execute a clean tracking reinitialization sequence:

    rm -rf node_modules package-lock.json
    npm install

🧱 4. Query Architecture Mismatches​

Missing Base Structural Type Identifier​

Exception: Missing query type

Resolution Runbook​

Ensure all instantiated queries explicitly chain an operational execution mutation pattern immediately before mapping properties or filtering logic blocks:

// ❌ Ambiguous initialization
const query = new ZTeraDBQuery("user");

// ✔ Correct architectural declaration
const query = new ZTeraDBQuery("user").select();

Empty Field Array Payload Constraints​

Exception: Fields not provided for INSERT or UPDATE

Resolution Runbook​

Mutation chains modifying entity states must pass non-empty dataset objects containing column-value mappings to the .fields() handler:

  // ✔ Correct fields mutation pattern
const query = new ZTeraDBQuery("user")
  .insert()
  .fields({ 
    email: "test@example.com" 
  });

🔍 5. Functional Filter Tree Errors​

Invalid Functional Parameter Layout​

Exception: Invalid parameters passed to ZTMUL

Root Cause​

Passing individual arguments sequentially to structural calculation functions instead of supplying them inside a unified matrix context.

Resolution Runbook​

Enclose target calculation parameters inside a singular structural array wrapper:

// ❌ Incorrect argument structure
ZTMUL("price", "quantity");

// ✔ Correct processing format
ZTMUL(["price", "quantity"]);

Structural Expression Mapping Mismatch​

Exception: Invalid filter: expected array

Resolution Runbook​

Ensure logical operator array components receive multi-layered condition sets properly nested within an array wrapper context:

// ✔ Wrap conditional rules inside a primary wrapper block
ZTAND([condition1, condition2]);

🧪 6. Production Debugging Runbooks​

When diagnosing complex state mutations or conditional failures, execute these verification methodologies:

Runbook 1: Inspect Compiled Statement State​

Call .generate() to extract and read the JSON query definition before running it over network connections.

console.log(query.generate());

Runbook 2: Test Isolated Isolation Baselines​

Isolate schema logic parameters from execution blocks by testing connectivity health using a basic table selection command:

const userQuery = new ZTeraDBQuery("user").select();

Runbook 3: Profile Active Credentials Matrix​

Over 90% of initialization issues stem from malformed security strings or environment objects. Validate credentials directly inside your runtime context using print statements or error logging layers.

🆘 7. Escalation & Technical Support​

If you encounter persistent infrastructural bugs or execution roadblocks outside the scope of this reference matrix, reach out to our core systems engineering department:

  • Provide the exact system exception dump message.
  • Supply the compiled evaluation output from query.generate().
  • Include a minimal reproducible code snippet showcasing the active connection profile context.