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

# Max Iterations Exceeded

> The agent loop ran the configured maximum number of iterations without converging on a final answer.

**Surface:** `GET /agents/runs/{id}`, `error.type = "AgentLoopMaxIterationsExceeded"`

## When this error occurs

Each run's `effective_config.max_iterations` caps how many inference rounds the workflow will
attempt before giving up. If the model keeps emitting tool calls without producing a final
answer, the workflow terminates with this error rather than running indefinitely.

The cap acts as both a safety net (against runaway tool-loops) and a cost ceiling — each
iteration costs one inference job.

## How to fix

Depending on the cause:

* **Cap is too low** — increase `max_iterations` in `defaults` (for the conversation) or in
  `config_override.max_iterations` (per-run). The cap of 3 is a sensible default for trivial
  prompts; multi-step research flows often need 8–15.
* **Model is looping** — examine the message stream. Repeated calls to the same tool with the
  same arguments suggest the prompt isn't giving the model enough information to terminate.
  Improve the system prompt, narrow the tool catalog, or pre-fill more context in the user
  message.
* **One tool is unreliable** — repeated failures from the same MCP tool can also cause looping.
  Check `tool_result.is_error` patterns in the message stream.