Troubleshooting

Most RetainDB issues come from five places:

1. API key missing or exposed in the wrong place.
2. Project or scope mismatch.
3. Source not indexed yet.
4. Async memory writes not visible immediately.
5. Agent prompt does not tell the model to use RetainDB.

Quick Triage

I Get 401

Check:

• RETAINDB_API_KEY exists where the server or MCP process runs
• request sends Authorization: Bearer ... or X-API-Key
• key starts with rdb_
• key was not rotated
• call is not happening in browser-side code

Dashboard users do not use API keys. Agents and servers do.

Company Brain Is Empty

Check:

1. Same project in dashboard, MCP, HTTP, and SDK.
2. Source status is ready or indexed.
3. Query mentions something actually present in the source.
4. Source is not paused or deleted.
5. API key has access to the project/source.

Useful command:

curl "https://api.retaindb.com/v1/sources?project=production" \
  -H "Authorization: Bearer $RETAINDB_API_KEY"

Source Sync Failed

Check:

• latest error message
• account connection or token validity
• whether the source type is actually enabled
• include/exclude rules
• file size or crawl limits
• retry count and last attempted time

Fix the source, then trigger sync again from the dashboard or:

curl -X POST "https://api.retaindb.com/v1/sources/src_123/sync" \
  -H "Authorization: Bearer $RETAINDB_API_KEY"

Memory Search Is Empty After Write

Check:

• same project
• same user_id
• same session_id if session-scoped
• query is semantically related to the memory
• include_pending: true immediately after async writes

Async writes are normal. They keep app latency low while indexing happens in the background.

MCP Agent Cannot Use RetainDB

Check:

• MCP host was restarted after config changes
• RETAINDB_API_KEY, RETAINDB_API_URL, and RETAINDB_PROJECT are in the MCP server env
• host supports local command MCP servers
• list_sources works before testing context

Ask the agent:

Call list_sources in RetainDB and report the project and source statuses.

Model Responses Ignore RetainDB

Check:

• the app actually injects RetainDB context into model messages
• the system prompt says to use RetainDB when relevant
• the model is told not to guess when context is missing
• top_k or max_results is not too low
• source context is not too noisy

Good instruction:

Use RetainDB context as evidence. If RetainDB does not answer the question, say what is missing.

What To Include In Support Reports

Include:

• trace_id
• project name/id
• route or MCP tool used
• source id if source-related
• timestamp
• expected behavior
• actual behavior

Do not include API keys, full private documents, or full customer transcripts.

Next: Errors, Sources API, or MCP Setup.