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

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.

High-availability issues

When running multiple Dakera nodes, retrieval inconsistencies are usually caused by embedding model mismatches or HNSW cache divergence:

• Different results per request (inconsistent recall) — All nodes must use the same embedding model. Verify DAKERA_EMBEDDING_MODEL is identical across nodes. A mismatch causes embedding vectors to occupy different spaces, making cross-node recall non-deterministic.
• HNSW cache miss on follower nodes — After bulk inserts, follower caches need time to sync. Set DAKERA_HNSW_CACHE_WARM=1 to eagerly warm cache on startup. For time-sensitive workloads, pin read traffic to the leader temporarily.
• Leader election loops — If nodes continually elect new leaders, check network latency between nodes (should be <5ms). High latency triggers spurious leader timeouts. Set DAKERA_RAFT_HEARTBEAT_MS to 3× your measured inter-node latency.
• Split-brain after network partition — Dakera uses a quorum model: a majority of nodes must agree before writes commit. A partition with no quorum causes writes to stall (not silently corrupt). Resolve by restoring network connectivity; no manual recovery is needed.

Knowledge graph not extracting entities

Entity extraction runs automatically on every stored memory by default. If entities aren't appearing:

• Extraction disabled — Check DAKERA_ENTITY_EXTRACTION=false is not set in your environment. Re-enable by removing the variable or setting it to true.
• Batch extraction not applied to old memories — Entity extraction runs on new memories. To extract entities from existing memories, use the bulk extraction endpoint: POST /v1/entities/extract-batch with your namespace and a date range.
• Low recall from graph traversal — Graph traversal uses entity links. If the agent ID used during recall differs from the one used when storing memories, graph links won't be found. Verify consistent agent_id values across write and read paths.
• Custom entity types not recognized — Configure custom extractors via PUT /v1/extractors/{namespace}. See API reference for the extractor schema.

Cross-agent recall not working

Cross-agent memory sharing requires explicit configuration and a compatible memory stored in the source agent's namespace:

• Verify cross-agent recall is enabled — Include cross_agent: true in recall requests. Without this flag, recall is scoped to the current agent_id only.
• Source agent must have memories — Check the source agent has stored relevant memories: GET /v1/agents/{source_id}/sessions.
• Namespace boundary blocks sharing — Cross-agent recall crosses agent boundaries within the same namespace. Memories in different namespaces cannot be recalled cross-agent. Both agents must use the same namespace.
• Importance floor filters too aggressively — Cross-agent recall applies the same importance floor as local recall. If source memories have decayed below your min_importance threshold, they won't surface. Lower the threshold or re-store with higher importance.

Memory decay not working as expected

• Decay not running — Decay runs on a schedule controlled by DAKERA_DECAY_INTERVAL_HOURS (default: 24). Check the server logs for decay_run events. If you need more frequent decay, lower the interval.
• All memories decaying too fast — Store important memories with higher importance scores (importance: 0.9) and configure namespace policy with a longer half-life: dk namespace policy set my-ns --decay-half-life 720h.
• Memories not decaying despite low importance — Memories with expires_at: null are pinned and never decay. Check for pinned memories: GET /v1/agents/{id}/sessions?pinned=true.
• Recall quality improving after decay — This is expected and by design. Old, low-importance memories stop polluting results as they decay below the recall threshold. If this behavior is undesired, disable decay: DAKERA_DECAY_ENABLED=false.

# Check namespace decay configuration
curl http://localhost:3300/v1/namespaces/my-namespace/policy \
  -H "Authorization: Bearer dk-your-key"
# → {"decay_half_life_hours":168,"decay_enabled":true,"min_importance_threshold":0.15,...}

Performance profiling

Use GET /admin/stats to identify bottlenecks before tuning:

curl http://localhost:3300/admin/stats -H "Authorization: Bearer dk-your-key"
# → {"memory_count":42801,"p50_recall_ms":12,"p99_recall_ms":87,"cache_hit_rate":0.91,...}

• p99 recall > 200ms — Increase HNSW cache: DAKERA_HNSW_CACHE_MAX=50000. If cache_hit_rate is <0.8, the working set is too large for your current cache allocation.
• High store latency — Embedding generation is the bottleneck for writes. Enable inference concurrency: DAKERA_INFERENCE_THREADS=4. For very high write throughput, use the batch store endpoint: POST /v1/memory/batch.
• BM25 index rebuild causing latency spikes — BM25 indexes rebuild incrementally. If you batch-imported many memories, a one-time rebuild spike is normal. It completes in the background and read latency recovers automatically.
• Consolidation impact on performance — Background consolidation (DBSCAN-based dedup) can briefly increase CPU load. Schedule it during off-peak hours via DAKERA_CONSOLIDATION_HOUR=3 (runs at 3 AM UTC).

Backup and restore issues

• Creating a backup — Use POST /admin/backup to trigger a consistent snapshot of the RocksDB data directory. The backup writes to the path set by DAKERA_BACKUP_PATH.
• Restore failing — Stop the server before restoring. Replace the data directory with the backup, then restart. Never restore into a running server.
• Backup size unexpectedly large — RocksDB stores compaction artifacts. Run POST /admin/compact before taking a backup to reduce size by 20–40%.
• Cross-version restore — Backups are compatible across patch versions (0.11.x → 0.11.y). Minor version restores (0.11 → 0.12) require running the included migration: dakera migrate --from-backup /path/to/backup.

TLS and certificate issues

• Certificate not found at startup — Verify the cert and key files are mounted into the container and the paths match DAKERA_TLS_CERT and DAKERA_TLS_KEY.
• TLS handshake failures from SDK — If the server uses a self-signed certificate, configure your SDK to trust the CA: DAKERA_CA_CERT=/path/to/ca.pem in the SDK environment. In production, use a trusted CA (Let's Encrypt or your org's PKI).
• Certificate expiry — Dakera logs a warning 30 days before certificate expiry. Monitor the tls_cert_expires_days metric in the Prometheus scrape endpoint (/metrics).

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, curl http://localhost:3300/admin/stats, and docker logs dakera --tail 50
• Specify your deployment mode (single-node Docker, HA, bare metal) and the failing operation