Troubleshooting

Common issues and how to fix them. Always start with the health endpoint:

curl http://localhost:3300/health
# {"service":"dakera","status":"healthy","version":"0.11.77"}

Server not starting

Check container logs first: docker logs dakera --tail 50. Common causes:

• Port conflict — Change DAKERA_PORT and the -p mapping
• Volume permission error — Ensure the data directory is writable
• Missing API key — Set DAKERA_ROOT_API_KEY

Authentication errors (401)

All authenticated requests need: Authorization: Bearer <your-api-key>. In SDKs, pass via DAKERA_API_KEY env var or the constructor parameter. Verify the key matches DAKERA_ROOT_API_KEY on the server.

No memories returned from recall

• Wrong agent_id — Recall is scoped to a single agent. Verify it matches exactly.
• Nothing stored yet — Confirm with GET /v1/agents/{id}/sessions.
• min_importance filter too high — Lower or remove the filter.
• Query too different — Try a query closer to stored text to verify retrieval works.

Slow queries

• First request after startup — ONNX models load on first use; expect 1–2 s cold start.
• Large index — Above 1M vectors, tune DAKERA_HNSW_CACHE_MAX and use SSD storage.

Connection refused

• Verify the server is running: docker ps | grep dakera
• Use the server's public IP when running remotely, not localhost
• Check firewall rules for port 3300

MCP server not connecting

• Use an absolute path to the MCP binary and ensure it's executable
• Verify DAKERA_API_URL points to your running server
• Fully restart Claude Desktop / Claude Code after editing config
• Run the MCP binary directly in a terminal to see errors

Embedding failures

Dakera uses a built-in ONNX embedding model. Common failure modes:

• Model not found at startup — The model is embedded in the binary and extracted on first run to a temp dir. Ensure the container has write access to /tmp.
• OOM during embedding — Reduce concurrent requests or increase container memory (--memory 1g recommended minimum).
• Embedding returns zeros / low recall quality — Verify the DAKERA_EMBEDDING_MODEL env var matches across all nodes if running HA. Mixed model versions cause incompatible embedding spaces.

# Check embedding model in use
curl http://localhost:3300/health
# → {"status":"ok","embedding_model":"nomic-embed-text-v1.5",...}

Docker networking

Common container networking issues:

• SDK can't reach server from another container — Use the service name, not localhost: http://dakera:3300 inside the same Docker network.
• Port not accessible from host — Confirm -p 3300:3300 and that no firewall blocks the port (ufw allow 3300 on Ubuntu).
• Container exits immediately — Missing required env vars. Check logs: docker logs dakera --tail 20. DAKERA_ROOT_API_KEY is required.

# Test connectivity between containers
docker exec my-app-container curl -s http://dakera:3300/health

Rate limiting (429 Too Many Requests)

Dakera applies per-key rate limits. If you're hitting 429s:

• Check the Retry-After header in the response
• Increase limits with DAKERA_RATE_LIMIT_RPM env var (default: 1000 req/min per key)
• For bulk imports, use batched store calls or the import API: POST /admin/memories/import

Storage and data issues

• Disk full — RocksDB writes fail silently until disk is full. Monitor with GET /admin/stats and set up disk alerts. Use POST /admin/namespaces/{ns}/optimize to reclaim space after large deletes.
• Data not persisting across restarts — Verify a volume is mounted: -v /data/dakera:/data. Without a volume, data lives only in the container layer.
• Memory importance decaying unexpectedly — The decay engine runs on a schedule. Increase importance at store time (0.9+) or set expires_at: null to prevent expiry. Verify DAKERA_DECAY_ENABLED is not set to false in environments where you expect decay.

API key issues

• 403 Forbidden — The key exists but lacks the required scope. Create a key with the correct scope: Admin for management operations, ReadWrite for normal use.
• Lost root API key — The root key is set via DAKERA_ROOT_API_KEY env var. Rotate by restarting the container with a new value. All existing data persists — only the authentication credential changes.
• SDK ignoring env var — Set DAKERA_API_KEY in the process environment, not just the shell. In Docker, pass via -e DAKERA_API_KEY=dk-xxx.

Getting help

If these steps don't resolve your issue:

• Open an issue at github.com/Dakera-AI/dakera-deploy/issues with your server version and logs
• Include the output of curl http://localhost:3300/health and docker logs dakera --tail 50