🛠 ZTeraDB Troubleshooting Guide

If you see errors like:

Connection failed
Invalid configuration
FilterCondition error
ModuleNotFoundError: No module named 'zteradb'
Could not connect to host

This guide will help you fix them quickly.

---

🔑 1. Configuration Errors

❌ Error:

Missing or invalid client_key / access_key / secret_key

✔ Fix:

Make sure your .env contains all required fields:

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

ZTERADB_HOST=db1.zteradb.com
ZTERADB_PORT=7777
ZTERADB_ENV=dev

Load them correctly:

import os
os.getenv("CLIENT_KEY")

---

❌ Error:

Invalid value for env

✔ Allowed values:

dev
staging
qa
prod

Ensure you're passing:

env=ENVS("dev")

---

🌍 2. Connection Errors

❌ Error:

Connection refused

✔ Fix:

• Check host → must be something like: db1.zteradb.com
• Check port → usually: 7777
• Ensure Firewall / VPN / WiFi isn't blocking outbound TCP
• Make sure your cluster is up

---

❌ Error:

Connection timeout

✔ Fix:

Test reachability:

curl http://db1.zteradb.com:7777

If unreachable → restart internet or check ZTeraDB dashboard.

---

❌ Error:

ModuleNotFoundError: No module named 'zteradb'

✔ Fix:

pip install zteradb

If using a virtual environment:

source venv/bin/activate

---

📦 3. Import / Class Errors

❌ Error:

ImportError: cannot import name 'ZTeraDBConfig'

✔ Fix: Make sure correct import syntax is used:

from zteradb.zteradb_config import ZTeraDBConfig

---

🧱 4. Query Errors

❌ Error:

Missing query type: select / insert / update / delete

✔ Fix:

ZTeraDBQuery("user").select()

---

❌ Error:

Fields required for INSERT or UPDATE

✔ Fix:

query.insert().fields({"email": "test@test.com"})

---

🔍 5. FilterCondition Errors

❌ Error:

Invalid parameters passed to ZTMUL

✔ Fix: Always pass lists:

ZTMUL(["price", "quantity"])

---

❌ Error:

Invalid filter: expected list of conditions

✔ Fix:

ZTAND([condition1, condition2])

---

🧪 7. Debugging Tips

✔ Tip 1 — Print Raw Query

print(query.generate())

✔ Tip 2 — Try a Simple Query

ZTeraDBQuery("user").select()

✔ Tip 3 — Re-check Keys

Most errors come from wrong client/access/secret key values.

---

🆘 Still Not Working?

Share the exact error message — I will fix it immediately.

---