# 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:

```sh
export OPENAI_API_KEY=...
cass check
cass
```

Fix in PowerShell:

```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:

```sh
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:

```json
{ "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:

```sh
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](configuration.md), and run:

```sh
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.

## 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:

```sh
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.