Reference
Errors and troubleshooting
The error vocabulary clai returns, what each meaning points at, and the switches that show more.
On this page
Every failure clai can report is one meaning from a closed vocabulary in pkg/claierr. The CLI prints the meaning and exits non-zero. The same values are available to Go programs that use pkg/agent, so a program can test a failure with errors.Is instead of matching on text.
The message is the meaning, then what the provider said: the status, the provider code, and the provider’s own message when a decoder read one.
Error vocabulary
| Sentinel | Meaning | What to check |
|---|---|---|
ErrAuthFailed |
authentication failed |
The vendor API key in the environment, and the endpoint it is sent to. |
ErrLikelyInsufficientCredits |
likely insufficient credits |
The vendor account balance or quota. |
ErrModelNotFound |
model not found |
The model name in the config file or the -cm, -pm or -vm flag. |
ErrRateLimited |
rate limited |
The vendor’s rate limit and the reset time it reported. |
ErrProviderUnavailable |
provider unavailable |
The vendor’s status page; try another vendor with the same profile. |
ErrTransport |
transport failure |
The network, a proxy, or the endpoint URL. |
ErrUnexpectedProviderResponse |
unexpected provider response |
The raw body that follows the message; the vendor changed its response shape. |
ErrContextLengthExceeded |
context length exceeded |
The conversation size; start a new chat or lower -mt (-max-tokens). |
ErrContentFiltered |
content filtered |
The prompt or the model’s answer, which the vendor refused. |
ErrMcpServerStartup |
mcp server startup failed |
The MCP server command, its arguments, and its environment. |
ErrMcpConnClosed |
mcp connection closed |
Whether the MCP server exited. |
ErrMcpFrameUndecodable |
mcp frame could not be parsed as JSON-RPC |
The MCP server’s output: it must be JSON-RPC on a clean stdout. |
ErrMcpAuthChallenge |
mcp endpoint demands authorization |
The MCP server’s token; run clai mcp auth <server> for an OAuth server. |
ErrMcpTransport |
mcp transport failure |
The MCP URL and its network path. |
ErrMcpHttpStatus |
mcp endpoint returned a failing status |
The HTTP status the MCP endpoint returned. |
ErrMcpUnsupportedContentType |
mcp endpoint returned an unsupported content type |
The MCP endpoint: it must answer with JSON. |
ErrMcpRPCError |
mcp server returned a JSON-RPC error |
The JSON-RPC error the server returned, which names the failing call. |
A response can carry more than one meaning. A 429 for an empty account is both rate limited and likely out of credits; clai reports both.
Debug output
Set DEBUG to any non-empty value to print request and tool lifecycle logs:
DEBUG=1 clai -t q "List the files in this directory"Set DEBUG_OUTPUT_FILE to send that output to a file and keep the terminal clean:
DEBUG=1 DEBUG_OUTPUT_FILE=/tmp/clai-debug.log clai q "Explain the last command"Related
- CLI reference lists the flags the error messages name.
- MCP and tools covers MCP server setup.
- Vendors lists the keys and endpoints each vendor needs.