# Errors and troubleshooting

> The error vocabulary clai returns, what each meaning points at, and the switches that show more.

Canonical URL: https://www.clai.chat/docs/reference/errors/ · Version: 1.0 · Updated: 2026-10-22

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

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:

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

```sh
DEBUG=1 DEBUG_OUTPUT_FILE=/tmp/clai-debug.log clai q "Explain the last command"
```

## Related

- [CLI reference](/docs/reference/cli/) lists the flags the error messages name.
- [MCP and tools](/docs/guides/mcp-and-tools/) covers MCP server setup.
- [Vendors](/docs/reference/vendors/) lists the keys and endpoints each vendor needs.