🛠 ZTeraDB Troubleshooting Guide

If you see errors like:

Compiled with problems
Connection failed
Invalid configuration
FilterConditions error
Cannot find module 'zteradb'

This guide will help you fix them quickly.

---

🔑 1. Configuration Errors

❌ Error:

Missing or invalid clientKey / accessKey / secretKey

✔ Fix:

Make sure your .env contains all required fields:

ZTERADB_CONFIG={
  "clientKey": "<Your ZTeraDB client key>",
  "accessKey": "<Your ZTeraDB access key>",
  "secretKey": "<Your ZTeraDB secret key>",
  "databaseID": "<Your ZTeraDB database id>",
  "env": "<Your working environment one of prod/staging/qa/dev>",
  "responseDataType": "json"
}

---

❌ Error:

JSON.parse error for ZTERADB_CONFIG

✔ Fix:

Your .env must have valid JSON.

Check for:

• Missing quotes
• Trailing commas
• Wrong brackets

---

🌍 2. Connection Errors

❌ Error:

Connection refused

✔ Fix:

• Check host
  Must be something like:
  db1.zteradb.com
• Check port
  Usually: 7777
• Check internet/firewall/VPN

---

❌ Error:

ECONNRESET
ETIMEDOUT

✔ Fix:

• Retry connection
• Ensure no firewall blocks outbound TCP
• Ensure server is reachable

---

📦 3. Import Errors

❌ Error:

Cannot find module 'zteradb'

✔ Fix:

Install it:

npm install zteradb

Or reinstall:

rm -rf node_modules package-lock.json
npm install

---

🧱 4. Query Errors

❌ Error:

Missing query type

✔ Fix:

Always call .select(), .insert(), .update(), or .delete().

new ZTeraDBQuery("user").select();

---

❌ Error:

Fields not provided for INSERT or UPDATE

✔ Fix:

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

---

🔍 5. FilterConditions Errors

❌ Error:

Invalid parameters passed to ZTMUL

✔ Fix:

Pass array values only:

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

---

❌ Error:

Invalid filter: expected array

✔ All logical and conditional filters accept arrays:

ZTAND([condition1, condition2]);

---

🧪 7. Debugging Tips

✔ Tip 1 — Log Your Query

console.log(query.generate());

✔ Tip 2 — Try Simple Query First

If nothing works:

new ZTeraDBQuery("user").select();

✔ Tip 3 — Check Keys Again

99% issues occur due to incorrect credentials.

---

🆘 If Still Not Working

Share the error message, and We’ll fix it immediately.

---