Troubleshooting

A problem during a turn shows as a message in the chat, a refused action shows where you clicked, and quiet problems wait in the Activity list.

Errors and anything that needs you stay on screen until you dismiss them; warnings are also kept in the sidebar's Activity view. From Terminal, bandicot rpc prints the error code and message.

First steps for any problem: wait for the running turn to finish, try again once, and if it repeats, quit and reopen Bandicot. Your chats and settings live outside the app and are kept.

A provider error names its HTTP status, and the status tells you whether to reconnect, pay, pick another model or wait.

A rate limit that says when to retry is waited out inside the turn when the wait is short. A plan limit on a signed-in account counts as spent until it resets.

When a conversation no longer fits the model, Bandicot compacts it and retries; with compaction off the turn ends with context overflow.

Turn Context compaction back on in Settings › Capabilities, run /compact, or start a new session. A session that grows past what Bandicot can continue says This session is too large to continue. Start a new one.

A turn that ends with stalled: stopped itself because the agent repeated the same tool calls, no tool call succeeded, or it kept hitting the same error. Read the last tool rows, correct the task and send it again.

When the agent calls a TypeSafe model and it fails, the tool result says why, and the status in the message tells you whether to reconnect or wait.

These appear in the tool row of the chat, not as a banner, and the agent reads them and can try again. Connect TypeSafe in Settings › Model.

A tool refuses with a plain reason when a file is outside the project, in a private place or changed since the agent read it; the reason names the fix.

The agent reads the reason and adapts, so you usually only see it in the tool row. Every refusal and what to change is listed with the agent's tools and private places.

Voice, the agent's browser, Team channels and local models each run as a helper, and Activity shows a line when one restarts, stops or cannot start.

Open the Activity view of the sidebar to see the line. A helper that crashed once restarts by itself and the line reads restarted after a crash with the time; it stays for half an hour unless you dismiss it. If it crashes twice within two minutes it stays stopped, Activity says stopped with the reason 2 crashes in 2 minutes, and a notice with Restart appears. A line that reads could not start gives the reason after it.

Restart is on the browser and Team channels lines. If it fails the line adds that restart did not go through, so try again. The voice helper has no button: it starts again the next time you open the voice window. A local model has no button either: it starts again when you choose it. Move over the Activity list to find a small dot, Helpers, that lists every helper as running, idle or stopped. The Mac app describes the rest of the list.

Doctor lists the host state and health checks, and each check reads pass or check so you can see what to fix.

Open Home, then the Account card, and choose Doctor. It shows Session & kernel, with the plain readouts, and Health checks. A line that says check is the one to look at first.

A local model refuses to load when its file or runtime changed on disk; download it again or remove and add it in Models.

Bandicot never swaps in another model silently: when the chosen one cannot run, the turn says so and stops.

Most session errors ask for one thing: wait for the last step, free disk space, update Bandicot or start a new session.

Each message here is the engine's own wording, so the fix beside it is the one Bandicot itself suggests.

Versions never keeps history for a folder that holds Bandicot's own data, such as your home folder; open a project folder inside it instead.

Chat and tools still work in such a folder; only version history stays off. Pick a project folder when you want changes you can undo. Versions covers the rest.

When Bandicot and Bandicot Beta are both open, only one runs automations, setup and recovery; do that work in the app that owns the data, or quit it.

The message reads Another Bandicot app open on this Mac manages automations for this data. Change or run them there, or quit it and try again. The apps never take the data from each other by themselves. Bandicot Beta explains which one owns it.

Bandicot updates itself the next time you open it, and the top of the Activity list says when an update waits or fails.

Update waits: an agent is running clears when the work ends. Bandicot cannot update itself means the app sits in a folder you cannot change: move it to Applications. A failed install keeps the version you had, and download problems retry later by themselves.

Each engine error has a code and a message; find the code here for what it means and what to do.

Codes written in lower case with underscores reach the app exactly so. Some reach it in CamelCase on a few paths, such as StalePreview for stale_preview.