Skip to main content

🛠 Troubleshooting

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

📌 Table of Contents​

🔑 1. Configuration Diagnostics​

Mismatched or Null Credential Exception​

Exception: Missing or invalid client_key / access_key / secret_key

Root Cause​

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

Resolution Runbook​

  1. Inspect your localized root .env configuration file for syntax completeness:

    CLIENT_KEY=your-client-key
    ACCESS_KEY=your-access-key
    SECRET_KEY=your-secret-key
    DATABASE_ID=your-database-id

    ZTERADB_HOST=<Your ZTeraDB HOST>
    ZTERADB_PORT=<Your ZTeraDB PORT>

  2. Ensure your runtime architecture possesses active dot-env parsing helpers or read your host properties cleanly:

      // Verify output returns strings, not boolean false values
      var_dump(getenv('CLIENT_KEY'));

Environment Stage Out-of-Bounds Error​

Exception: Invalid value for env

Resolution Runbook​

Ensure that the env string value targeted inside your connection configuration uses one of the following strict schema definitions:

dev | staging | qa | prod

🌍 2. Network & Connection Diagnostics​

Socket Connection Refused​

Exception: Connection refused (or socket error 111)

Resolution Runbook​

  • Endpoint Validation: Confirm that the destination host (ZTERADB_HOST) and targeted application port (ZTERADB_PORT) match your infrastructure provisioning profile (Default target: db1.zteradb.com:7777).

  • Network Isolation Policies: Verify that corporate firewall rules, local VPN tunnels, or security groups allow outbound TCP handshakes over the assigned port spectrum.

Connection Timeout Interval Breach​

Exception: Connection timeout (ETIMEDOUT)

Resolution Runbook​

  1. Trigger an internal trace route or simple socket verification sequence directly from your local terminal cluster: 
    telnet youtzteradbhost 7777
  2. If network paths drop without returning headers, inspect system latency rates or introduce retry loops around your driver setup instances.

📦 3. Namespace & Autoloader Diagnostics​

Class Definition Undefined Exception​

PHP Fatal error: Class "ZTeraDB\Config\ZTeraDBConfig" not found

Root Cause​

The Composer class-mapping engine has an un-synchronized tracking index or the critical autoloader utility script hasn't been required in your application entry points.

Resolution Runbook​

  1. Re-index and optimize class definitions within your execution tree:

    composer dump-autoload

  2. Ensure your entry-point code pattern embeds the vendor registration layer prior to calling ZTeraDB query namespaces:

    <?php   
      require_once __DIR__ . '/vendor/autoload.php';
    ?>

🧱 4. Query Architecture Mismatches​

Missing Base Structural Type Identifier​

Exception: Missing query type: select / insert / update / delete

Resolution Runbook​

Ensure all instantiated queries explicitly chain an operational execution mutation pattern immediately before mapping properties or filtering logic blocks:​
// ❌ Ambiguous initialization
$query = new ZTeraDBQuery('user');

// ✔ Correct architectural declaration
$query = (new ZTeraDBQuery('user'))->select();

Empty Field Array Payload Constraints​

Exception: Fields are required for INSERT or UPDATE

Resolution Runbook​

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

$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:

// ❌ 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:

// 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.

echo $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:

$users = $db->run((new ZTeraDBQuery('user'))->select()->limit(0, 1));

Runbook 3: Profile Active Credentials Matrix​

Over 90% of initialization issues stem from malformed security strings. Validate credentials directly inside your runtime 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.