---
title: "Errors"
url: "/docs/harness/errors"
canonical_url: "https://docs.litellm.ai/docs/harness/errors"
type: "docs"
last_updated: "2026-10-01"
summary: "Setup problems raise an exception. Limits you set, like timeout and maxturns, end the turn and return a Result with a stopreason, so partial work is kept."
related:
  - "/docs/harness/api_reference"
  - "/docs/set_keys"
---
# Errors

> Index of all LiteLLM docs: https://docs.litellm.ai/llms.txt


Setup problems raise an exception. Limits you set, like `timeout` and `max_turns`, end the turn and return a `Result` with a `stop_reason`, so partial work is kept.

All exceptions below except `TypeError` and `ValueError` subclass `litellm.harness.HarnessError`.

| Exception | Raised when | Raised at |
|---|---|---|
| `TypeError` | `harness` isn't a `Harness` member. The message names the member you probably meant. | call |
| `ValueError` | a `litellm_proxy/` model is used without a gateway base URL or key | call |
| `CapabilityUnsupported` | the harness can't do what you asked, for example `permissions="edit"` on Codex or `tools=` on Claude Code | before the runtime starts |
| `OptionsMismatch` | options for a different harness, or a native config key LiteLLM manages | call |
| `HarnessInstallFailed` | the runtime binary isn't on the sandbox's `PATH`, or Deep Agents' packages aren't installed | session start |
| `SandboxError` | the sandbox failed to start, run a command or reach the host | any time |
| `SessionClosed` | a turn on a session that is closed or detached | turn start |
| `StateIncompatible` | `agent_resume()` with a state from a different harness or an unreadable version | resume |
| `OutputInvalid` | the final answer didn't validate against `output=` | turn end |

## Stop reasons

| `stop_reason` | Meaning |
|---|---|
| `"done"` | the runtime finished its turn |
| `"max_turns"` | reached `max_turns` tool calls |
| `"timeout"` | the turn ran longer than `timeout` seconds |
| `"cancelled"` | the turn was cancelled |
| `"runtime_error"` | the runtime process exited on its own; `Result.text` has its last stderr lines |

## Model errors during a turn

Provider errors inside a turn, such as rate limits and 5xx responses, aren't raised. The runtime usually retries them itself, and on the gateway they show up as failed requests in the spend logs with the harness tag.

Error messages never include your virtual key, provider keys or the session token.

## Related pages

- [API reference](https://docs.litellm.ai/docs/harness/api_reference.md)
- [Setting API Keys, Base, Version](https://docs.litellm.ai/docs/set_keys.md)