Troubleshooting

Most RetainDB issues come from auth, scope mismatch, or expecting async writes to behave like blocking writes.

I get 401

Check:

• RETAINDB_API_KEY is set where the server process runs
• the request includes Authorization: Bearer ... or X-API-Key
• the key was not pasted incorrectly or rotated
• the call is not happening in browser-side code

I wrote memory but search is empty

Check:

• same project
• same user_id
• same session_id if session-scoped
• include_pending: true immediately after async writes
• query is related to what you stored

Agent context is empty

Check:

• same project
• same task_id
• the agent recorded events or durable task memory first
• the query asks for something related to the recorded events
• handoff context was created before resume

Model responses ignore memory

Check:

• you actually inject context into the model messages
• your system message does not tell the model to ignore external context
• top_k is not too low
• the memory was stored under the same user or task scope

Vercel or build fails

Docs are static MDX, but the frontend app also builds API routes. If build fails in an unrelated route, check required environment variables for that route in Vercel.

Next: Release checklist.