Reference

Errors and troubleshooting

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

On this page

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.

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.

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

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