Skip to main content

🛠 Troubleshooting

This diagnostic directory provides immediate resolution paths for configuration mismatches, network timeout exceptions, import blocks, and query structure anomalies within the ZTeraDB Python 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 configuration 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
   ZTERADB_ENV="dev"
  1. Ensure your runtime architecture possesses active dot-env parsing helpers and verify your environment handles return actual values instead of None:
import os
from dotenv import load_dotenv

load_dotenv()
# Verify output returns strings, not None
print(repr(os.getenv("CLIENT_KEY")))

Environment Stage Out-of-Bounds Error​

ValueError: 'INVALID_ENV' is not a valid ENVS

Root Cause​

Passing an unsupported string environment value to the runtime configuration initializer.

Resolution Runbook​

Ensure that the ZTERADB_ENV string value targeted inside your connection configuration maps precisely to the valid enumeration instances of the ENVS class: DEV | STAGING | QA | PROD

env=ENVS.DEV

OR

env=ENVS("dev")

🌍 2. Network & Connection Diagnostics​

Socket Connection Refused​

ConnectionRefusedError: [Errno 111] Connect call failed

Resolution Runbook​

  • Endpoint Validation: Confirm that the destination host (ZTERADB_HOST) and targeted application port (ZTERADB_PORT) match your infrastructure provisioning profile (Default target: Your ZTeraDB HOST:Your ZTeraDB PORT).
  • 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​

asyncio.exceptions.TimeoutError or OSError: [Errno 110] Connection timed out

Resolution Runbook​

  1. Test target infrastructure accessibility and connection paths directly from your terminal engine using network tools:
telnet Your ZTeraDB HOST Your ZTeraDB PORT
  1. If network paths drop without returning headers, inspect system latency rates or check your active ZTeraDB cloud cluster instance panel dashboard.

📦 3. Import & Namespace Diagnostics​

Dependency Base Missing Exception​

ModuleNotFoundError: No module named 'zteradb'

Root Cause​

The active environment scope does not have the core engine package assembled inside its workspace index.

Resolution Runbook​

Install the package directly inside your active interpreter shell space:

pip install zteradb

If you utilize managed virtual configurations, make sure the environment is explicitly activated before launching your script pipeline:

source venv/bin/activate

Namespace Allocation Failure​

ImportError: cannot import name 'ZTeraDBConfig'

Resolution Runbook​

Ensure your code strictly references the correct internal file and class namespace structures layout:

# ❌ Incorrect legacy import configuration
from zteradb.zteradb_config import ZTeraDBConfig

# ✔ Correct structural importing
from zteradb.config.zteradb_config import ZTeraDBConfig

🧱 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 = ZTeraDBQuery("user")

# ✔ Correct architectural declaration
query = 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 dictionaries containing key-value pairs to the .fields() handler:

query = (
    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 list wrapper ([...]):

# ❌ Incorrect argument structure
ZTMUL("price", "quantity")

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

Structural Expression Mapping Mismatch​

Exception: Invalid filter: expected list of conditions

Resolution Runbook​

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

# Wrap conditional rules inside a primary list 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 raw compiled query definition before executing it over active socket handles.

print(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:

result = await db.run(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 script context using standard loggers or terminal stream print engines.

🆘 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 and traceback stack.
  • Supply the compiled evaluation output from query.generate().
  • Include a minimal reproducible code snippet showcasing the active connection profile context.