Troubleshooting

This page helps you fix a failed call quickly. Look up the error code, read what it means and follow the fix. The last section helps when your AI client misses a tool.

#How errors look

Every error carries a stable code, a readable message, a retryable flag and details.

Over REST, the error comes with an HTTP status:

{"request_id": "req_...", "error": {"code": "NOT_FOUND", "message": "...", "retryable": false, "details": {}}}

Over MCP, the tool result says "ok": false:

{"ok": false, "error": {"code": "NOT_FOUND", "message": "...", "retryable": false, "details": {}}}

Retry only when retryable is true, or when you send the same idempotency key. See Idempotency keys.

To try the examples below, first create a small object:

{"tool": "schema_define_object", "arguments": {"name": "contact"}}

{"tool": "schema_define_field", "arguments": {"object": "contact", "name": "score", "type": "integer"}}

{"tool": "records_create", "arguments": {"object": "contact", "data": {"score": 50}}}

#VALIDATION_ERROR and related codes

Meaning: the input breaks a rule. Nothing was written. Related codes are more specific:

• FIELD_TYPE_MISMATCH: a value does not fit the field type.
• UNKNOWN_FIELD: the object has no field with that name.
• REQUIRED_FIELD_MISSING: a required field has no value.
• INVALID_QUERY: a filter, operator or sort is not allowed.
• INVALID_CURSOR: a cursor does not belong to this query.

curl -X POST https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"object":"contact","data":{"score":"high"}}'

What to do: read message and details. They name the field and the rule. Fix the input and send it again. Check the schema with schema_inspect when you are unsure.

#VERSION_CONFLICT

Meaning: someone changed the record after you read it. Your update named an old version. Nothing was written.

{"tool": "records_update", "arguments": {"record_id": "$REC", "version": 7, "data": {"score": 60}}}

What to do: read the record again with records_get. Apply your change to the new values. Send the update with the new version. details.current_version shows the version to expect.

#NOT_FOUND

Meaning: the record, object, file or workspace does not exist. You also get NOT_FOUND for a workspace your key cannot reach. AgentDB does not tell the two cases apart, on purpose.

{"tool": "records_get", "arguments": {"record_id": "rec_aaaaaaaaaaaaaaaaaaaaaaaaaa"}}

What to do: check the id and the workspace. Run workspace_list to see the workspaces your key reaches.

#RATE_LIMITED

Meaning: you sent too many requests in a short time. The error is retryable.

What to do: wait, then retry. When details.retry_after_seconds is present, wait that long. Use the same idempotency key for a write. Send bulk data in batches with records_upsert_batch instead of one call per record.

#QUOTA_EXCEEDED

Meaning: the workspace is full, or it reached a limit such as the number of saved views. AgentDB refuses new writes. Reading keeps working.

What to do: delete records or files you no longer need. Run workspace_info or agentdb workspace info to see your quotas and use.

#UNSUPPORTED_OPERATION

Meaning: this server has no operation with that name. The name may be misspelled or from another version.

{"tool": "agentdb_execute", "arguments": {"operation": "records_teleport", "arguments": {}}}

What to do: do not retry the same name. details.available_operations lists names you can use. Or search with agentdb_capabilities. See Discover operations.

#APPROVAL_REQUIRED

Meaning: an approval policy covers this write. A person must approve it first. Nothing was written.

What to do: do not retry the write. Propose it with approvals_submit, with the tool name, its arguments and a reason. A person approves or rejects it in the AgentHub. The change runs once when approved. See Hub and approvals.

#Sign-in and key errors

These errors mean AgentDB does not accept your key, or your key may not do this. The CLI exits with code 3 for all of them.

• UNAUTHENTICATED (HTTP 401): the key is missing, wrong, revoked or expired.
• FORBIDDEN (HTTP 403): the key is valid, but its role or scopes do not allow this call.
• NOT_LOGGED_IN (CLI only): the CLI has no saved key and no AGENTDB_TOKEN.
• WORKSPACE_SUSPENDED or WORKSPACE_PENDING_DELETION (HTTP 403): the workspace is closed for now.

curl https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/schema \
  -H "Authorization: Bearer adbk.not-a-real-key"

What to do:

1. Check the header. It must be Authorization: Bearer, one space, then the full key.
2. In the CLI, run agentdb login --api-url https://app.agentdb.link again.
3. For FORBIDDEN, ask a workspace owner or admin for the access you need.
4. Lost or leaked key? See Accounts and security.

#CLI exit codes

The CLI prints JSON to standard output. Its exit code tells a script what happened:

agentdb records get rec_aaaaaaaaaaaaaaaaaaaaaaaaaa

A bulk upsert with any failed item also exits with code 2.

#My AI client does not see a new tool

Your AI client loads the tool list when it connects. It keeps that list until it reconnects. So after an AgentDB update, a new tool can be missing.

1. Start a new chat. Many clients reload the tool list then.
2. Still missing? Reconnect the client. In claude.ai, disconnect and connect the AgentDB connector. In Claude Code, run /mcp, choose agentdb and reconnect.
3. In ChatGPT, refresh the connector, or remove it and add it again.

Your agent can also work without a reload. It calls agentdb_capabilities with client_tools, the names of the tools it has. The answer lists what it misses. It then runs each missing operation through agentdb_execute.

{"tool": "agentdb_capabilities", "arguments": {"client_tools": ["records_create", "records_query"]}}

#Still stuck?

Note the request_id from the error response. It helps support find your request.