| 1 | import type { DocsTroubleshootingDict } from "../types"; |
| 2 | |
| 3 | /** |
| 4 | * English reference dictionary for `app/[locale]/docs/troubleshooting/page.tsx` |
| 5 | * ("Fix a problem"). Error texts and fixes come from docs/INSTALL.md §13 |
| 6 | * (every one was hit while writing that guide), docs/OPERATIONS_RUNBOOK.md, |
| 7 | * docs/KEYBINDINGS.md (Ctrl-B), crates/tui/src/runtime_log.rs (log path), |
| 8 | * and docs/DOCKER.md. |
| 9 | */ |
| 10 | export const docsTroubleshooting: DocsTroubleshootingDict = { |
| 11 | metaTitle: "Fix a problem · Codewhale Docs", |
| 12 | metaDescription: |
| 13 | "Diagnose Codewhale in one command, then fix the common problems: command not found, no reply, a rejected key, network errors, a stuck turn, a session that will not resume, and MCP servers.", |
| 14 | bodyClassName: "text-ink-soft leading-relaxed", |
| 15 | title: "Fix a problem", |
| 16 | lede: |
| 17 | "Start with one diagnostic command, then find your symptom below. Each fix names the exact message you will see.", |
| 18 | sections: [ |
| 19 | { |
| 20 | id: "diagnose", |
| 21 | title: "Run the diagnostics", |
| 22 | blocks: [ |
| 23 | { |
| 24 | code: `codewhale --version |
| 25 | codewhale doctor |
| 26 | codewhale doctor --probe-api # one real test call to your provider |
| 27 | codewhale auth status --provider deepseek # which key is in use`, |
| 28 | lang: "Terminal", |
| 29 | }, |
| 30 | { |
| 31 | p: "`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.", |
| 32 | }, |
| 33 | ], |
| 34 | }, |
| 35 | { |
| 36 | id: "install", |
| 37 | title: "Install and update", |
| 38 | blocks: [ |
| 39 | { |
| 40 | rows: [ |
| 41 | ["`codewhale: command not found`", "`~/.local/bin` is not on your PATH in this terminal. Add `export PATH=\"$HOME/.local/bin:$PATH\"` to your shell profile and open a new terminal."], |
| 42 | ["`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 its `bin` to your PATH, and install again."], |
| 43 | ["`refusing to replace existing ~/.local/bin/codewhale`", "A different version is already there. Run `codewhale update`, or remove the old binaries first."], |
| 44 | ["`checksum mismatch`", "The download was corrupted or altered, and nothing was installed. Try again; if it repeats, do not use a mirror."], |
| 45 | ["`The package-managed executable was not changed.`", "You installed with npm, Cargo, or Homebrew. Update with that tool, for example `npm install -g codewhale`."], |
| 46 | ], |
| 47 | }, |
| 48 | ], |
| 49 | }, |
| 50 | { |
| 51 | id: "model", |
| 52 | title: "No reply, or the key is rejected", |
| 53 | blocks: [ |
| 54 | { |
| 55 | rows: [ |
| 56 | ["Your message appears but nothing answers", "No key is configured, and v0.10.0 does not warn you. Press F3, choose your provider, and paste the key."], |
| 57 | ["`API key not found`", "No key anywhere. Save one with `codewhale auth set --provider <name>`."], |
| 58 | ["`Authentication Fails … is invalid`", "The key is wrong or revoked. Run `auth status` to see which source is used — a saved key beats an environment variable — then save the right key or `codewhale auth clear --provider <name>`."], |
| 59 | ["`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, export `HTTPS_PROXY`. On Windows or strict proxies, try `CODEWHALE_FORCE_HTTP1=1`."], |
| 60 | ], |
| 61 | }, |
| 62 | ], |
| 63 | }, |
| 64 | { |
| 65 | id: "turn", |
| 66 | title: "A turn is stuck", |
| 67 | blocks: [ |
| 68 | { |
| 69 | list: [ |
| 70 | "Press Esc to cancel the turn. Esc also closes menus first, so press it again if a menu was open.", |
| 71 | "If a long shell command is holding the turn, press Ctrl-B to move it into the background. The turn continues, and `/jobs` shows the command.", |
| 72 | "`/retry` sends the last request again.", |
| 73 | ], |
| 74 | }, |
| 75 | { |
| 76 | p: "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/`.", |
| 77 | }, |
| 78 | ], |
| 79 | }, |
| 80 | { |
| 81 | id: "sessions", |
| 82 | title: "Resume a session", |
| 83 | blocks: [ |
| 84 | { |
| 85 | code: `codewhale sessions # list saved sessions |
| 86 | codewhale resume <id> # an id or a unique prefix |
| 87 | codewhale -c # the latest session in this folder`, |
| 88 | lang: "Terminal", |
| 89 | }, |
| 90 | { |
| 91 | p: "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.", |
| 92 | }, |
| 93 | { |
| 94 | p: "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.", |
| 95 | }, |
| 96 | ], |
| 97 | }, |
| 98 | { |
| 99 | id: "mcp", |
| 100 | title: "MCP tools are missing", |
| 101 | blocks: [ |
| 102 | { |
| 103 | list: [ |
| 104 | "After changing `mcp.json` or a server's credentials, run `/mcp reload`. `/mcp validate` only refreshes what you see.", |
| 105 | "Run the server's command yourself in a shell to confirm it starts.", |
| 106 | "If the config file is missing or broken, `codewhale mcp init --force` writes a fresh one.", |
| 107 | ], |
| 108 | }, |
| 109 | ], |
| 110 | }, |
| 111 | { |
| 112 | id: "docker", |
| 113 | title: "Run in Docker", |
| 114 | blocks: [ |
| 115 | { |
| 116 | code: `docker volume create codewhale-home |
| 117 | docker run --rm -it \\ |
| 118 | -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \\ |
| 119 | -v codewhale-home:/home/codewhale/.codewhale \\ |
| 120 | -v "$PWD:/workspace" -w /workspace \\ |
| 121 | ghcr.io/codewhale-hq/codewhale:latest`, |
| 122 | lang: "Terminal", |
| 123 | }, |
| 124 | { |
| 125 | p: "The image runs as a non-root user and keeps your settings and sessions in the named volume. Pin a release tag instead of `latest` for repeatable setups, use one volume per project, and never bake keys into an image.", |
| 126 | }, |
| 127 | ], |
| 128 | }, |
| 129 | ], |
| 130 | next: [ |
| 131 | { |
| 132 | href: "/docs/auth", |
| 133 | label: "Connect a provider", |
| 134 | note: "Save a key, check which one is used, or switch to a local model.", |
| 135 | }, |
| 136 | { |
| 137 | href: "/install", |
| 138 | label: "Install Codewhale", |
| 139 | note: "Every install method, with the output each step should print.", |
| 140 | }, |
| 141 | { |
| 142 | href: "/docs/review", |
| 143 | label: "Review what changed", |
| 144 | note: "Roll files back to the snapshot before a turn went wrong.", |
| 145 | }, |
| 146 | ], |
| 147 | sourceNote: |
| 148 | "Source documents: docs/INSTALL.md §13, docs/OPERATIONS_RUNBOOK.md, docs/DOCKER.md · Update docs-map.ts when changing.", |
| 149 | }; |
| 150 |