Troubleshooting
What to check when a provider fails, a command waits, or a feature won't start.
A provider keeps failing
A turn retries rate limits, overloads, server errors and dropped connections by itself. It makes 3 attempts. Then, when the provider is down, it makes up to 5 recovery waits of 15 to 60 seconds. Raise or lower both in General settings. Test Connection on the provider checks the key or sign-in. /logs shows what failed.
The turn stopped early
Model calls per turn (100 by default) caps how often one turn may call the model. Disable the limit so that a turn runs until the model is done.
The agent is waiting
The status in the top bar says why: Needs approval (an approval card is at the bottom of the transcript), a question, or a plan. The sessions dock lists the sessions that wait for you under Attention.
A command is still running
Commands yield after 10 seconds and keep running. The prompt box's dock lists them. Use Stop for one command, or Stop all. Esc stops the turn but leaves its commands running.
A crew won't start
Choose the models in Crew Workflow first. /crew-supervised needs a Leader model and a Worker model. /crew-self-managed needs a Worker model. The project must be a git repository with at least one commit. No merge, rebase, cherry-pick or revert can be in progress, and the working tree cannot have unresolved conflicts.
A goal won't merge
You can't merge or discard a goal while a command that it polls is running. If your project changed under it, merging leaves the project as it was, and the goal says what blocked the merge.
The code graph isn't watching
Code graph can't watch this path in the status bar means that the code graph doesn't see file changes there as they happen.
Where's my data?
Settings, sessions and logs live in ~/.config/kc. Keys and sign-ins are in the system keychain. See Files & folders.