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. 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; 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:

{
  "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 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.
`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, retry with backoff. If sustained on one agent, pin a fallback model via 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 and check the agent’s tool chain for loops. Either fix the looping tool, or raise the ceiling with `latency_budget` (see 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.

Reference

Troubleshooting: agent runtime errors

Troubleshooting: agent runtime errors

Decision table — agent error → fix

Do not retry the deterministic codes

Distinguish timeout from runaway loops

When to escalate

See also

​Troubleshooting: agent runtime errors

​Decision table — agent error → fix

​Do not retry the deterministic codes

​Distinguish timeout from runaway loops

​When to escalate

​See also

Troubleshooting: agent runtime errors

Decision table — agent error → fix

Do not retry the deterministic codes

Distinguish timeout from runaway loops

When to escalate

See also