Troubleshooting
Agent isn’t responding
Check provider config, API key, network, blocking hooks — and isolate the problem layer by layer.
Symptom
You send a message in the Agent panel and nothing comes back: the input might spin forever on "Thinking...", it might silently do nothing, or it might flash a red toast that disappears too fast to read. The Agent will surface failures from the network, provider, hooks, and sidecar layers all as the same "no response".
Before triaging, do one thing: open a fresh chat (Cmd/Ctrl + N), type something tiny like ping, and watch what happens. If the fresh chat replies, the problem is context or message history. If the fresh chat also stalls, it is config or infrastructure.
Likely causes
- API key expired, revoked, or rate-limited by the upstream (most common — about 60% of cases)
- Provider endpoint misconfigured (base URL missing
/v1, using http instead of https) - The local Go sidecar process crashed — the UI is alive but nothing is answering the router
- A hook returned deny at PreToolUse, so the Agent has no usable tools
- OS firewall or corporate proxy is blocking outbound HTTPS
- Account balance / quota exhausted (the upstream returns 429 but the UI does not surface it)
Step-by-step diagnostic
Walk these in order — cheapest checks first, most invasive last:
- Settings → Providers — confirm the active provider shows a green "Ready" badge
- Hit the "Test" button on the provider row — it sends a minimal request and returns within 5s
- Open the logs folder (commands below) and scan the last minute for
errororpaniclines - In Activity Monitor / Task Manager, look for
kition-sidecarand confirm it is still running - Switch providers (e.g., temporarily add Anthropic if you were on OpenAI) — if the switch works, the original provider is the culprit
- Disable every hook (Settings → Hooks → disable all) and send one message
Useful log commands
On macOS, in Terminal:
# Tail the live agent log
tail -F ~/Library/Logs/Kition/agent.log
# Find recent errors across all logs
grep -inE "error|panic|429|401|500" ~/Library/Logs/Kition/*.log | tail -40
# Sidecar boot trace (look for "listening on")
grep -i "sidecar" ~/Library/Logs/Kition/main.log | tail -20Fix
- Key revoked: regenerate it in the provider console, paste back into Settings → Providers, Save → Test
- Sidecar dead: menu bar Kition → Restart Sidecar (or Cmd/Ctrl + Shift + R from Settings)
- Hook blocking: Settings → Hooks → find the PreToolUse rule, temporarily disable or fix its match
- Proxy / firewall: Settings → Network to set an HTTP_PROXY, or have IT allowlist
api.openai.comand friends - Quota: top up or upgrade your account; rate limits reset within ~60s
Workaround
If none of the above works, mount a fallback provider (any OpenAI-compatible endpoint — Together, Groq, a self-hosted vLLM) and set it as default to get unblocked. Switch back when the primary provider is healed.
Also: the editor and tables work fully without the Agent. Close the Agent panel and keep writing while you triage.
When to file a bug
- The "Test" button succeeds but real chats fail — router-layer bug
- Sidecar crashes repeatedly, dies again within 30s of restart
- Logs contain
panic:plus a Go stack trace - Same key works in the provider’s Playground but returns 401 in Kition