# Errors and troubleshooting

> How clai reports configuration, vendor, rate-limit, and tool errors, plus debugging flags.

Canonical URL: https://www.clai.chat/docs/v0.1/reference/errors/ · Version: 0.1 · Updated: 2026-10-21

Full site index: https://www.clai.chat/llms.txt

`clai` encodes every failure as a descriptive Go error returned up the call stack and exits non-zero on failure.

## Error taxonomy

| Code                | Reason            | Action             | Resolution                                                                                                 |
| ------------------- | ----------------- | ------------------ | ---------------------------------------------------------------------------------------------------------- |
| `INVALID_CONFIG`    | `MISSING_API_KEY` | `SET_ENV_VAR`      | Export the required vendor API key (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.).        |
| `INVALID_CONFIG`    | `UNKNOWN_MODEL`   | `RUN_SETUP`        | Run `clai setup` or pass a valid model identifier with `-cm`, `-pm`, or `-vm`.                             |
| `VENDOR_ERROR`      | `QUOTA_EXCEEDED`  | `BACKOFF_RETRY`    | Upstream vendor returned an HTTP or stream error.                                                          |
| `RATE_LIMITED`      | `QUOTA_EXCEEDED`  | `BACKOFF_RETRY`    | Upstream vendor returned HTTP 429; `clai` automatically waits and retries when a reset window is provided. |
| `CONTEXT_LENGTH`    | `TOKEN_LIMIT`     | `COMPACT_CONTEXT`  | Conversation or tool output exceeded the model context window; use tool truncation or start a fresh chat.  |
| `TOOL_FAILURE`      | `MCP_TIMEOUT`     | `CHECK_MCP_SERVER` | Builtin tool or MCP server failed or timed out; inspect with `DEBUG=1`.                                    |
| `TRANSCRIPT_IMPORT` | `INVALID_SESSION` | `RUN_SETUP`        | External vendor transcript could not be parsed or found.                                                   |

## File validation reasons

- `CONFIG_PARSE_ERROR` — a JSON file under `~/.config/clai/` contains invalid syntax.
- `PROFILE_NOT_FOUND` — the profile requested via `-p` or `-pr-path` does not exist.
- `SKILL_FRONTMATTER_INVALID` — a `SKILL.md` file is missing required YAML frontmatter (`name`, `description`).
- `TRANSCRIPT_NOT_FOUND` — the requested conversation or external vendor session file does not exist.

## Debugging with DEBUG and DEBUG_CALL_ID

Set `DEBUG=1` to print request/response lifecycle logs, or `DEBUG_CALL_ID=1` to inspect individual tool call identifiers:

```sh
DEBUG=1 DEBUG_CALL_ID=1 clai -t q "List files in the current directory"
```