> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting: agent runtime errors

> Decode AI-agent error codes — AGENT_ERROR, AGENT_NOT_CONFIGURED, AGENT_RESPONSE_INVALID, AGENT_EXECUTION_TIMEOUT, INVALID_MODEL, LLM_PROVIDER_ERROR — map each to its cause, fix the gate, and decide between retry and escalation.

# Troubleshooting: agent runtime errors

An agent run returns a non-2xx envelope, an SSE stream aborts with an error
event, or a conversation shows a failed turn in the
[Live tab](/agents/live-monitor). The `error.code` in the response tells you
which gate fired. This page covers the six codes the agent runtime throws, in
the order you will meet them. The full list of platform codes lives in the
[error reference](/reference/error-codes); this page gives you the fix for
each agent code.

A typical envelope looks like this — the `code` is the stable identifier you
key on, never the `message` text:

```json theme={null}
{
  "error": {
    "code": "AGENT_EXECUTION_TIMEOUT",
    "message": "Agent execution timed out. Please retry.",
    "status": 504
  },
  "meta": {
    "request_id": "req_01HZXK8FJ2",
    "timestamp": "2026-09-09T12:34:05.119Z"
  }
}
```

## Decision table — agent error → fix

| Code                      | HTTP | Cause                                                                                                                                                                                                         | Fix                                                                                                                                                                                                                                                                        |
| ------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AGENT_NOT_CONFIGURED`    | 422  | Deploy or run attempted on an agent with no `system_prompt` set.                                                                                                                                              | Set a system prompt on the agent (`PATCH /agents/:id` with `system_prompt`), then re-deploy. New agents start in `draft` — fill in the prompt before channel deployment.                                                                                                   |
| `INVALID_MODEL`           | 422  | The agent's `model` id is not in the supported allowlist — usually a legacy or misspelled id persisted on the agent.                                                                                          | Pick a supported id from [model selection](/agents/model-selection) and PATCH the agent. Known retired ids are re-mapped to their served replacement on save; a genuinely unknown id 422s at write time, not at run time.                                                  |
| `AGENT_RESPONSE_INVALID`  | 502  | The run completed but the response payload could not be parsed — the runtime returned malformed JSON for the turn.                                                                                            | Safe to retry once (the same input often succeeds). If it recurs on the same agent, shorten/clamp the prompt or attached tools — oversized outputs are the common cause — and check the failing turn in the [Live tab](/agents/live-monitor).                              |
| `LLM_PROVIDER_ERROR`      | 502  | Anthropic upstream failed — the model-call threw (overload, internal error, provider-side fault) before the turn completed.                                                                                   | Check the [status page](https://status.orbit.devotel.io), retry with backoff. If sustained on one agent, pin a fallback model via [model selection](/agents/model-selection) where your fallback policy lives.                                                             |
| `AGENT_ERROR`             | 502  | Catch-all: the runtime connection failed, or the upstream returned an error envelope without a narrower code.                                                                                                 | Read the accompanying `message` first — the platform propagates the runtime's structured envelope when one was sent. If `message` is empty after this page, collect the `request_id` from `meta` and escalate.                                                             |
| `AGENT_EXECUTION_TIMEOUT` | 504  | The turn exceeded the execution ceiling — the default 30-second platform ceiling, or your per-agent `config.latency_budget.turn_ms` override (1 000–180 000 ms). A runaway tool-call loop is the usual cause. | Inspect the failing conversation in the [Live tab](/agents/live-monitor) and check the agent's tool chain for loops. Either fix the looping tool, or raise the ceiling with `latency_budget` (see [cost controls](/agents/cost-controls) for the adjacent iteration caps). |

## Do not retry the deterministic codes

Three of these codes re-fail deterministically — a retry re-runs the same
gate and returns the same code:

* **`AGENT_NOT_CONFIGURED`** — the prompt is still missing until you write
  one.
* **`INVALID_MODEL`** — the model id is still illegal until you pick a
  supported one.
* **A capped or gated run** (cost caps, guardrails) — same input, same gate.

Retry only the transient ones: `LLM_PROVIDER_ERROR` (provider blip),
`AGENT_RESPONSE_INVALID` (occasionally), and `AGENT_EXECUTION_TIMEOUT` after
you have removed the loop cause — otherwise the retry burns the 30-second
ceiling again.

Live-stream clients key on the same sanitised code set: the SSE path maps
upstream failures to stable machine codes (`LLM_RATE_LIMITED`,
`LLM_OVERLOADED`, `AGENT_EXECUTION_TIMEOUT`, …) so your client can branch on
`code`, not on a message string.

## Distinguish timeout from runaway loops

`AGENT_EXECUTION_TIMEOUT` has two very different causes and they pair with
different fixes:

* **A genuinely slow agent** — a deep-research prompt with a legal 30 s
  budget. Fix: set `config.latency_budget.turn_ms` (up to 180 000 ms) on the
  agent and retry.
* **A runaway tool loop** — the agent chains the same tool until the ceiling
  trips. Fix: inspect the run in the Live tab, find the repeating tool call,
  and correct the tool or the prompt that re-invokes it. Raising the ceiling
  hides the loop rather than fixing it; the parallel
  `tool_loop_limit` cap exists for that case.

## When to escalate

Escalate to support when:

* The same agent returns `AGENT_ERROR` with an empty or opaque `message`
  and you have ruled out the table above.
* `LLM_PROVIDER_ERROR` persists after the status page reports all
  operational.
* `AGENT_EXECUTION_TIMEOUT` fires on a turn with no tool calls at all —
  that should not reach the ceiling.

Include the `request_id` from the `meta` block of the failing response,
the agent id, and the conversation id. The request id threads through the
chat, stream, and invoke paths, so support can pull the executor-side trace
without a back-and-forth.

## See also

* [Error reference](/reference/error-codes) — the full code catalog this
  page's table maps.
* [Live conversation monitor](/agents/live-monitor) — read the failing turn
  before you decide which gate fired.
* [Agent model selection](/agents/model-selection) — the supported model
  allowlist an `INVALID_MODEL` references.
* [Agent cost controls](/agents/cost-controls) — the caps and iteration
  guardrails that also terminate runs.
* [Troubleshooting: agent eval-queue failures](/troubleshooting/agent-eval-queue) —
  the eval-pipeline sibling of this runbook.