Troubleshooting

Symptom	Fix
”Backend is not connected” in the UI	The backend isn’t on :8799, or (dev mode only) the two localStorage lines aren’t set. Set them in DevTools and reload — see Installation. The one-click start.command avoids this entirely.
uvx not found / tools show “no-tool”	Install uv (uvx ships with it), and make sure it’s on the PATH for the shell that runs uvicorn.
Literature sweep returns nothing	You’re offline (RC_OFFLINE=1) or tools are off (RC_USE_TOOLS=0); or the topic is too narrow — try the citation gate with specific claims.
claude_cli is slow / first call hangs	The CLI spins up a full agent (~3 s). Set RC_USE_CLI_PROVIDERS=0 to use Gemini directly (sub-second). See Providers.
Gemini calls return nothing	The model id may be invalid for your key — try RC_GOOGLE_MODEL=gemini-2.5-flash.
First tool call is very slow	The first call downloads ToolUniverse (~30 s, once). Subsequent calls are cached.
Reset all local data	rm backend/data/cockpit.db (rebuildable; gitignored), then re-seed.

Still stuck? Check the Agents / Runs screen — it shows every model and tool call with its provider and online/offline status, which usually points straight at the cause.