Start with fastdata doctor. It checks Node, the config, Claude credentials, the knowledge base
and the connector (including a test query), and says what to fix.
fastdata doctor
fastdata doctor --query "SELECT COUNT(*) FROM orders" # test a specific query
Setup
No fastdata.yaml found
Run fastdata from the folder that contains fastdata.yaml (or a subfolder), or pass
-c path/to/fastdata.yaml. Create one with fastdata init.
config.connector.env.DATABASE_URL: environment variable X is not set
The config references ${X}. Export it in your shell or add X=… to a .env file next to
fastdata.yaml.
fastdata.yaml is invalid
The message lists each wrong key. A common one: set exactly one of command (stdio) or url (http).
No answer, or an authentication error from Claude
Check that Claude Code is logged in (claude starts without asking you to log in), or set
ANTHROPIC_API_KEY. For Bedrock or Vertex AI, see
Configuration.
Node … Node 22.13+ is recommended
The SQLite demo and executor need node:sqlite. Upgrade Node.
Connector
Could not start the MCP connector … Connection closed
The server process exited. The error includes the server's own output under server output:;
usually it is a wrong path, a missing package or a bad connection string. Try running the
command and args from your config by hand.
Could not find a SQL tool on the connector
The server's tools are listed in the error. Set connector.tool (and connector.sql_arg if
needed) in fastdata.yaml.
Unrecognized result format
The connector returned something that is not rows (see
what a connector may return). If you wrote the
connector, return { "columns": [...], "rows": [[...]] }.
The database returned an error: …
The agent sees this too and normally fixes the query itself. If it keeps failing, a table note in
the knowledge base is probably wrong or missing (wrong column name, wrong type).
Rejected before execution: …
fastdata's read-only guard blocked the query. If a column is named like a SQL keyword, quote it
("update"). Backslashes inside quotes are not allowed; use chr(92) or LIKE … ESCAPE '!'.
Text that databases read differently is rejected too: nested /* comments, #, -- without a
space after it, quotes inside [ ], and $$…$$ strings whose contents are not also valid SQL
(use '…').
The agent normally rewrites the query on its own.
Answers
The answer is wrong
Read the answer's Assumptions, Query and Based on. Then fix the knowledge base: a
glossary entry for the business word, a metric definition, or a note on the table. Add the
corrected question and query to examples/ so it stays right. See
how to grow the knowledge base.
Stopped after 30 steps without an answer
The question was too broad, or the knowledge base did not help the agent find the tables. Ask
something more specific, improve INDEX.md, or raise max_turns.
Answers are slow or expensive
Each turn and cost is shown under the answer. Broad questions make the agent read many files.
A clear INDEX.md with a "question → where to look" table helps most. You can also use a
cheaper model (model: claude-sonnet-5-5) or effort: low for simple data.
Web chat
The web UI is not built
You are running from source without a build. Run npm run build.
Port 8000 is taken
fastdata picks the next free port automatically and prints the URL. Or use --port.
This conversation is still answering the previous message
Wait for the current answer, press Stop, or start a New chat.
Result expired or not found
Results are kept in memory while the server runs (the last 200). Ask the question again after a
restart.