Skip to content

Troubleshooting

Most problems have a quick fix. Find yours below, and if it isn’t here, the logs usually say what went wrong.

When a reply can’t finish, the conversation says why: Send failed, Run failed, or Stopped before a response. Choose Retry to try again. Any part of the reply that already arrived stays visible, and if there was an earlier reply, Show previous reply brings it back.

If retrying fails again, check your provider below.

  1. Open Settings → LLM Provider and select the provider.
  2. Choose Test Connection.
  3. If it fails, check the API key, and the base URL for self-hosted or custom providers. For a local model in Ollama or LM Studio, make sure it is running.

An error such as Insufficient credits comes from your provider: top up your account with them. See AI Providers for setup details.

If the conversation shows The current model does not support tool calling, the model can only chat. Switch to a model that supports tools; ChatShell knows which ones do.

If the model supports tools, check that the tool is turned on in the conversation settings, and in Settings → Built-in Tools.

No vision-capable model configured means your current model can’t see images. Either switch to one that can, or add a vision model in Settings → Auxiliary Models, and keep your main model. See Auxiliary Models.

In Ask and Auto mode, commands run inside your system’s sandbox. When one needs to reach the internet or change files outside the allowed folders, ChatShell shows a card where you can Run once outside sandbox or Allow network this session.

In Auto mode, the review may block an action you want. Choose Run anyway once the reply finishes. If Auto blocks several actions in a row, ChatShell suggests switching to Ask, so you approve each one yourself.

Auto is unavailable for this model means the model can’t review actions, so the conversation uses Ask. See Permissions and Sandbox.

The AI reads videos with ffmpeg. Install it, for example with brew install ffmpeg on macOS, winget install ffmpeg on Windows, or your Linux package manager, then attach the video again.

Ask for it directly: “Show me a chart.” If it still arrives as code, check that Chart and data blocks (OpenUI) is on in Settings → Visuals. See Charts and Diagrams.

Some pages only load in a full browser. In Settings → Web Fetch, choose Always use system WebView, or Always use Chrome for the best compatibility. See Web Fetch.

Windows builds aren’t code-signed yet, so SmartScreen may say Windows protected your PC. Choose More info, then Run anyway.

See Cross-Device Sync for how sync works and the manual controls.

Open Settings → Advanced:

  • Log Storage shows how much space the logs use. Choose Open Logs Directory to see the files, and set a size limit to keep them small.
  • Diagnose with AI starts a conversation that reads ChatShell’s recent logs, finds errors and repeating failures, and suggests fixes.
  • Backend Log Level and Frontend Log Level control how much detail is written. Raise them while you reproduce a problem, then lower them again.

Report an issue on GitHub. Include what you did, what happened, and the relevant lines from the logs. Issues get a first response within a week.