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.55"}

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