Troubleshooting

#401 Not authenticated: valid session or API key required

• The key is missing, mistyped, or has been revoked. Print its length rather than the key itself to check it was read from the environment.
• The key was sent as Authorization: Bearer …. Send it as X-API-Key: … instead.
• The environment variable was set in a different shell from the one running your code.

#401 This API key is agent-scoped and cannot be used on this endpoint

You called a route with no agent in its path, such as GET /v1/agents. A key only works on routes under /v1/agents/{agent_id} for its own agent. To list agents, use the app — or, with the MCP server, the list_agents tool, which lists the agents you configured keys for.

#403 This API key is not valid for this agent

The agent_id in the URL is not the agent the key was issued for. Each key belongs to exactly one agent; generate a key on the other agent's Share → API panel and keep a key per agent.

#404 Session … not found for agent …

The session_id came from a different agent, or from a different installation. Leave session_id out to start a new conversation.

#400 with provider_key_missing

Your account answers with its own OpenAI key and none is saved. Add it on the app's Credentials screen. The same code with provider_key_invalid or provider_key_rejected means the saved key is wrong or out of credit.

#429 Query limit reached

Your account asked 20 questions in the last 24 hours. The message says when you can ask again. Scheduled jobs, MCP sessions and the app all share this limit, so a busy job can use it up for everyone on the account. See Question limits.

#The answer says it cannot determine the result

is_answered is false and the text explains the data does not hold the answer — for example asking for customers by region when the customers table has no region. Check which tables the agent may use in the app, and add table or column descriptions that use the words your users ask with.

#sql_query or db_result is missing

• The request did not set "debug_info": true.
• The agent's Settings → Answers hides SQL or results. That setting wins over the request.

#No chart_output

Charts are suggested only when the result suits one and the agent's chart setting allows it. Ask explicitly ("Show a bar chart of …") and send "chart_output": true.

#Requests time out

Answers take 10–30 seconds and sometimes longer. Raise your client timeout to 120–180 seconds. In browsers and serverless functions with short limits, call the API from a background job instead, or use streaming so the connection shows progress.

#EventSource never delivers the final answer

The stream's final line is full_metadata: …, which is not a standard event field, so EventSource drops it. Read the stream line by line as shown in Streaming.

#The MCP server is not connected

• claude mcp list shows Pending approval: start claude in the project folder and approve the project's server once.
• command not found / failed to start: the client cannot find database-agent-mcp. Give its full path in the configuration, or install it into the Python environment the client uses.
• The server exits at start: no credential is set. Check DATABASE_AGENT_AGENT_KEYS is set in the environment Claude Code starts from, in the form AGENT_ID=KEY.
• No credential configured for agent …: the tool was asked about an agent that has no key in DATABASE_AGENT_AGENT_KEYS.

#Still stuck

Collect the request (without the key), the status code, the detail, and the trace_id or chat_id from the response, and open an issue on GitHub or contact FutureSmart.