Fix a problem
Start with one diagnostic command, then find your symptom below. Each fix names the exact message you will see.
Run the diagnostics
Terminal
codewhale --version codewhale doctor codewhale doctor --probe-api # one real test call to your provider codewhale auth status --provider deepseek # which key is in use
codewhale doctor --json produces a diagnostics bundle without secrets, ready to attach to an issue. Plain doctor does not tell you which key is active and exits successfully even with no key; use auth status for that.
Install and update
codewhale: command not found~/.local/binis not on your PATH in this terminal. Addexport PATH="$HOME/.local/bin:$PATH"to your shell profile and open a new terminal.npm error code EACCES- Your Node install is owned by the system. Do not use sudo: point npm at a folder you own with
npm config set prefix "$HOME/.npm-global", add itsbinto your PATH, and install again. refusing to replace existing ~/.local/bin/codewhale- A different version is already there. Run
codewhale update, or remove the old binaries first. checksum mismatch- The download was corrupted or altered, and nothing was installed. Try again; if it repeats, do not use a mirror.
The package-managed executable was not changed.- You installed with npm, Cargo, or Homebrew. Update with that tool, for example
npm install -g codewhale.
No reply, or the key is rejected
- No answer arrives
- Check
codewhale --version: in v0.10.2, a missing model keeps your message in the composer and opens provider setup, so connect a model and send it again. If setup is complete, checkcodewhale auth status --provider <name>, then runcodewhale doctor --probe-apifor your selected hosted route orcodewhale doctor --probe-localfor a local model; these probes contact the service. API key not found- No key anywhere. Save one with
codewhale auth set --provider <name>. Authentication Fails … is invalid- The key is wrong or revoked. Run
auth statusto see which source is used — a saved key beats an environment variable — then save the right key orcodewhale auth clear --provider <name>. Network error: SSE stream request failed …- Usually no connection to the provider. Check with
curl -sI https://api.deepseek.com(a 401 means it is reachable). Behind a proxy, exportHTTPS_PROXY. On Windows or strict proxies, tryCODEWHALE_FORCE_HTTP1=1.
A turn is stuck
- Press Esc to cancel the turn. Esc also closes menus first, so press it again if a menu was open.
- If a long shell command is holding the turn, press Ctrl-B to move it into the background. The turn continues, and
/jobsshows the command. /retrysends the last request again.
For a detailed record, start Codewhale with RUST_LOG=codewhale_tui=debug (or RUST_LOG=codewhale_tui::client=debug for connection retries). Logs are written to ~/.codewhale/logs/.
Resume a session
Terminal
codewhale sessions # list saved sessions codewhale resume <id> # an id or a unique prefix codewhale -c # the latest session in this folder
Inside Codewhale, Ctrl-R opens the session picker. No saved sessions found for workspace after codewhale exec --continue means the earlier run was a plain exec, which is not saved; use --output-format stream-json for runs you want to continue.
Messages you send while offline wait in a queue, saved with the session. /queue list shows them. When the connection is back, open one with /queue edit <n> and press Enter to send it.
MCP tools are missing
- After changing
mcp.jsonor a server's credentials, run/mcp reload./mcp validateonly refreshes what you see. - Run the server's command yourself in a shell to confirm it starts.
- If
mcp.jsonis missing,codewhale mcp initcan create it. Back up an existing file before repair;--forcereplaces its configuration.
Run in Docker
Terminal
docker volume create codewhale-home docker run --rm -it \ -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \ -v codewhale-home:/home/codewhale/.codewhale \ -v "$PWD:/workspace" -w /workspace \ ghcr.io/hmbown/codewhale:v0.10.0
This uses the image and v0.10.0 tag documented in the Docker guide. It runs as a non-root user; keep settings in the named volume, use one volume per project and never bake keys into the image.
Next
Connect a provider
Save a key, check which one is used, or switch to a local model.
Install Codewhale
Every install method, with the output each step should print.
Review what changed
Roll files back to the snapshot before a turn went wrong.