Troubleshooting
Most problems have a quick fix. Find yours below, and if it isn’t here, the logs usually say what went wrong.
A reply failed or stopped
Section titled “A reply failed or stopped”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.
Your provider won’t connect
Section titled “Your provider won’t connect”- Open Settings → LLM Provider and select the provider.
- Choose Test Connection.
- 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.
The AI isn’t using tools
Section titled “The AI isn’t using tools”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.
You can’t attach an image
Section titled “You can’t attach an image”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.
A command was blocked
Section titled “A command was blocked”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.
A video attachment shows no frames
Section titled “A video attachment shows no frames”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.
You asked for a chart and got text
Section titled “You asked for a chart and got text”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.
A web page comes back empty
Section titled “A web page comes back empty”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 warns about the installer
Section titled “Windows warns about the installer”Windows builds aren’t code-signed yet, so SmartScreen may say Windows protected your PC. Choose More info, then Run anyway.
Sync isn’t up to date
Section titled “Sync isn’t up to date”See Cross-Device Sync for how sync works and the manual controls.
Check the logs
Section titled “Check the logs”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.
Still stuck?
Section titled “Still stuck?”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.