cassady/docs/troubleshooting.md

Troubleshooting

Use cass check first for configuration problems. It validates files, provider/model references, and authentication availability.

Missing active API key

Symptom: cass check reports that an environment variable is not set, or chat startup says the API key is not available.

Likely cause: the active provider's api_key is an env reference such as "$OPENAI_API_KEY", but that variable is not set in the current shell.

Fix on macOS/Linux:

export OPENAI_API_KEY=...
cass check
cass

Fix in PowerShell:

$env:OPENAI_API_KEY = "..."
cass check
cass

Missing or expired ChatGPT Codex auth

Symptom: cass check reports Codex auth errors, or chat startup says provider authentication is not available for chatgpt-codex.

Likely cause: ChatGPT Codex is active but $CODEX_HOME/auth.json or ~/.codex/auth.json is missing, unreadable, lacks tokens.access_token, or contains an expired token.

Fix:

codex login
cass check
cass

You can also sign in with the Codex app if that is how your local Codex auth is managed. Cassady does not refresh or store ChatGPT/Codex tokens; it reads local Codex auth at check/request time and redacts secret values.

Invalid API key reference

Symptom: the key is not resolved the way you expect.

Likely cause: Cassady only treats strings that start with $ as environment references. It does not expand partial strings or ${NAME} syntax.

Fix:

{ "api_key": "$OPENAI_API_KEY" }

Provider URL unreachable

Symptom: setup model discovery fails or a turn reports a provider error.

Likely causes:

• wrong base_url;
• network or proxy problem;
• provider outage;
• provider requires a different OpenAI-compatible path;
• for ChatGPT Codex, the private ChatGPT backend endpoint changed or the selected model is unavailable.

Fix: verify the base URL in providers.json, retry setup, or enter the model id manually if only /models discovery is failing. For ChatGPT Codex, verify that base_url is https://chatgpt.com/backend-api/codex/responses, rerun codex login, and try a current Codex model id.

/models discovery fails

Symptom: setup cannot fetch models.

Likely cause: some providers do not expose GET /models, require extra permissions, or return a non-standard shape.

Fix: choose retry if the failure is temporary; otherwise enter the model id manually. Then run cass check.

Unsupported or invalid model id

Symptom: chat starts but the provider rejects the model.

Likely cause: the model id in models.json or config.json is not valid for the provider.

Fix: update the model id with cass setup, edit models.json, or launch with:

cass --model MODEL_ID

Then verify with a small prompt.

Rate limit or authentication errors

Symptom: the assistant says the provider returned an error.

Likely cause: provider-side authentication, quota, billing, or rate limit. For ChatGPT Codex, this can also mean your ChatGPT subscription/account does not have the requested Codex model available or the local Codex token needs to be refreshed by Codex.

Fix: confirm the API key, provider account status, selected model, and provider dashboard. For ChatGPT Codex, rerun codex login or open Codex to refresh local auth. Cassady forwards provider failures into the chat but cannot resolve account-level issues.

Invalid JSON or unknown config fields

Symptom: cass check reports a parsing or schema error for config.json, providers.json, or models.json.

Likely cause: invalid JSON, comments, trailing commas, misspelled fields, or a field in the wrong file.

Fix: remove comments/trailing commas, compare against Configuration, and run:

cass check

Workspace access denied

Symptom: tool output says a path escapes allowed roots or workspace-edit root.

Likely cause: the active mode is read-only or workspace-edit, and the path resolves outside the launch cwd or bundled docs.

Fix: start from the intended project directory, pass --cwd PATH, or intentionally use --full-access when broad filesystem access is needed.

Shell unavailable or waiting for approval

Symptom: shell is denied or Cassady asks for approval.

Rules:

• read-only: shell is unavailable.
• workspace-edit: shell requires approval.
• full-access: shell is allowed by policy.

Fix: switch mode with Shift-Tab while idle or launch with the desired access flag.

Shell command failed or timed out

Symptom: shell result includes stderr, non-zero exit code, or timeout.

Likely cause: the command itself failed, the working directory is wrong, dependencies are missing, or the timeout was too short.

Fix: inspect stdout/stderr, verify cwd in /status, and ask Cassady to rerun the smallest relevant command.

Tool output was compacted or truncated

Symptom: a tool result note says Cassady compacted or truncated output, shows retained head/tail excerpts, or says a search stopped after a match limit.

Likely cause: the raw tool output exceeded the model-facing result limit or the active model context budget.

Fix: treat omitted output as incomplete. Ask Cassady to re-read the exact file line range named in the note, run a narrower grep query/path, lower max_matches, or rerun a shell command with a more focused flag/filter before making edits based on omitted lines.

Exact-text edit failed

Symptom: edit reports old_text not found, old_text is not unique, or overlapping edits.

Likely cause: the file changed, whitespace differs, line endings differ, or the replacement text is too broad.

Fix: ask Cassady to re-read the file and retry with a smaller unique old_text. For repeated blocks, include nearby unique context.

Binary, large, or unsupported files

Symptom: read/edit output is confusing or fails.

Likely cause: the file is binary, too large for useful display, or not valid UTF-8 for text edits.

Fix: ask Cassady to list metadata or use project-specific tools through approved shell commands. Avoid direct text edits on binary files.

CRLF or line-ending confusion

Symptom: exact-text edits fail even when the text appears to match.

Likely cause: Windows CRLF line endings or invisible whitespace differences.

Fix: re-read the exact target region and preserve the line endings in old_text, or use a smaller unique snippet.

Branch/restore file conflicts

Symptom: branch-plus-file restore reports conflicts or skips paths.

Likely cause: the file changed outside Cassady after the tracked write/edit, the file is unsupported for snapshots, or the change came from a shell command or manual editor rather than a Cassady file tool.

Fix: review the restore preview, inspect conflicted files manually, and rerun the menu with conversation-only branching if you only need to revisit the chat. Cassady will not overwrite unknown current content by default. Open the branch/restore menu again with double Esc or /branch to switch back to the original branch.

Update command problems

Symptom: cass update cannot complete.

Likely causes and fixes:

• Network or GitHub API failure: retry later or verify proxy/firewall settings.
• No matching prebuilt archive: use cass update --source if you have Rust installed, or download the release archive manually for a supported target.
• SHA-256 mismatch: do not install the archive. Retry the update; if it repeats, check the GitHub release page before proceeding.
• Missing Rust toolchain in source mode: install Rust/Cargo yourself, then rerun cass update --source. Cassady does not install Rust automatically.
• Non-writable install directory: update through the original install method, move Cassady to a directory you own, or manually replace the binaries. Cassady does not run sudo for you.
• PATH conflict: cass update updates the current executable directory. Run which cass / which cassady on macOS/Linux or Get-Command cass in PowerShell to confirm which binary your shell starts.
• Windows replacement limitation: if Cassady reports that automatic replacement is unavailable, use the staged file paths it prints and copy them after the running process exits.

Useful checks:

cass update --check
cass update --dry-run
cass --version
cassady --version

Terminal rendering problems

Symptom: the UI appears garbled or keys do not behave as expected.

Likely cause: unsupported terminal features, redirected stdin/stdout, or platform-specific terminal behavior.

Fix: run Cassady in an interactive terminal. Use cass check for non-interactive validation. Windows runtime polish is planned for a later release.

Setup says it is interactive

Symptom: cass setup fails with setup is interactive; run cass setup in a terminal.

Likely cause: stdin is not a terminal.

Fix: run setup directly in a terminal, not through a non-interactive script or redirected input.