Troubleshooting
Common errors when connecting to and using MarkDB, and how to fix them.
401 Unauthorized
- Missing or malformed key. Send
Authorization: Bearer mk_live_...(orx-api-keyon the Anthropic Messages surface). Keys start withmk_live_. - Revoked or wrong key. Check Settings -> API keys; a revoked key fails immediately. Mint a new one if you lost the plaintext (it's shown only once).
- A dashboard session against MCP. The MCP server accepts only
an API key, never a dashboard JWT. Use an
mk_live_key.
404 / "model not found"
The provider is chosen from the model name. If you get a 404 or a model-not-found error:
- Use a name that matches a routing prefix (
claude-*,gpt-*/o*,gemini-*,grok-*). - Add the matching provider credential under Settings -> LLM keys -- without it MarkDB can't call the upstream.
429 Too Many Requests
You hit the API rate limit on api.markdb.cloud/v1 (per tenant,
per minute). Respect the Retry-After header. Note the proxy and MCP
surfaces aren't rate-limited by MarkDB -- a 429 from those is your model
provider's own limit.
Search returns nothing
- Give enrichment a moment. Search reads summaries, which the worker produces in the background. Brand-new activity isn't searchable until it's been enriched and indexed.
- Check the embedder. Semantic (vector) recall needs the embedding provider's key configured under Settings -> LLM keys; if the embedder is unavailable, search falls back to keyword-only rather than failing.
- Widen the query. Try
mode: "text"for exact terms/IDs, or dropartifact_kind/min_importancefilters.
Summaries aren't appearing
The enrichment worker is likely backing off from a provider quota error (see Rate limits & quotas). Capture still works; only summaries lag. Check your provider key and its daily quota, and consider a higher-throughput enrichment model under Processing.
A chat split into many sessions
MarkDB derives a chat key from the opening messages to
hold a conversation together. If your client doesn't replay history or uses its
own threading, set the X-MarkDB-Chat-Key header. Also expected: after ~3h idle,
the next request rolls into a new session under the same chat -- that's the
idle-rollover behavior, not fragmentation.
Config changes didn't take effect
Processing settings are cached per tenant and take effect within about a minute. Changing the embedding model or dimensions triggers a re-index of existing pages.