Troubleshooting

The most common errors you'll hit, with the actual fix. If your symptom isn't listed, check docker logs svc-api and search the message verbatim against smart-memory-service/memory_service/api/.

Connection & infra

`ConnectionRefusedError: ... 9010` / `redis.exceptions.ConnectionError`

Cause: FalkorDB or Redis isn't running, or the API container can't reach them.

Fix:

docker compose ps
docker compose up -d falkordb redis mongodb
curl http://localhost:9001/health

If you're running the API outside Docker but databases inside, make sure FALKORDB_HOST=localhost, REDIS_HOST=localhost, MONGODB_HOST=localhost are set — the in-container defaults (falkordb, redis, mongodb) only resolve on the compose network.

`MongoServerSelectionTimeoutError`

Cause: MongoDB on 9013 isn't reachable. Auth metadata (users, workspaces, API keys, sessions) is in Mongo — without it, every /auth/* call 500s.

Fix: start the mongodb service and wait for the healthcheck to pass (docker compose ps mongodb).

Auth & tenancy

`401 Unauthorized` on every request

Cause: The access token is missing or expired.

Fix: In SDKs the RefreshManager rotates silently — if it's failing, clear local tokens and log in again. With curl, fetch a fresh token via POST /auth/refresh (with the refresh token) or POST /auth/clerk/session (with a Clerk JWT).

`400 Team context is required`

Cause: A team_required route was called without X-Workspace-Id / X-Team-Id.

Fix: Send the active workspace id in X-Workspace-Id. The JS SDK does this automatically once you call client.setTeamId(...).

`403 Forbidden` from an `/api-keys` endpoint

Cause: The active session doesn't own that key, or it's a superadmin endpoint and the user lacks the role.

Fix: Generate API keys under the same user that owns them. For ops queries, hold the superadmin role on UserResponse.roles.

Ingestion & pipeline

`WARNING: origin="unknown"` in logs

Cause: A caller invoked add() / ingest() without setting the MemoryItem.origin field. Items still ingest but bypass the origin-tier visibility policy.

Fix: Set origin="cli:add", origin="api:ingest", etc. on the MemoryItem you pass in. See smartmemory/origin_policy.py for the tier prefixes.

Empty entity results, no extraction

Cause: The LLM extractor is disabled (no API key) and the lite pipeline auto-degraded to keyword extraction. See PipelineConfig.lite() in smartmemory/pipeline/config.py — llm_enabled is auto-detected from OPENAI_API_KEY / GROQ_API_KEY.

Fix: Set one of those env vars, or pass llm_enabled=True explicitly. For the lite-mode degrade behaviour see Lite mode.

Ingest hangs / `IngestPaused`

Cause: An ontology migration is running and producer-side ingestion was paused (ONTO-RECONCILE-1).

Fix: Wait for the migration to finish, or run scripts/migrate_ontology_unify.py --status to confirm the MigrationState.ingest_paused flag. The orchestrator unpauses on every exit path; if the flag is stuck, manually call unpause_ingest.

`ValueError: 'working' is not a valid MemoryType`

Cause: Code or data still references the legacy memory_type="working".

Fix: Rename to pending (CORE-MEMORY-DYNAMICS-1 M1b). See Migration & upgrade.

Search

Search returns empty / irrelevant results

Cause one — empty vector index: After a backup restore or embedding-model upgrade, the vector index can desync from the graph. Run smartmemory-core rebuild to reindex from the graph snapshot.

Cause two — origin policy filters: Items with origin in tiers 3-4 (speculative / system) are excluded from default search. Pass origin="user" to broaden, or check smartmemory/origin_policy.py.

Cause three — wrong workspace: A common bug after switching teams in the UI is querying with the previous workspace token. Verify client.getTeamId().

Streaming / SSE

Progress stream never delivers events

Cause: Reverse-proxy buffering. nginx defaults buffer SSE.

Fix: Add proxy_buffering off; on the /memory/progress/stream location. Caddy handles SSE correctly out of the box.

`SSE connection failed: HTTP 400` with "Team context is required"

Cause: No X-Workspace-Id header on the SSE request.

Fix: Pass workspaceId to subscribeProgress({...}). See JavaScript SDK.

Storage growth

FalkorDB memory keeps climbing

Cause: Snapshots / sweeps disabled, every ingest version sticks around.

Fix: Enable retention sweepers:

SNAPSHOT_RETENTION_ENABLED=true
SNAPSHOT_RETENTION_INTERVAL_SECONDS=86400

Or run a one-shot POST /memory/summary/retention/sweep.

MongoDB disk full

Auth metadata, snapshots payloads, and admin logs live in Mongo. Drop old admin logs:

docker exec smartmemory-mongodb mongosh smartmemory \
  --eval 'db.admin_logs.deleteMany({created_at: {$lt: new Date(Date.now()-90*86400e3)}})'