run-llama/llama_index · error · WorkflowRuntimeError

Max iterations of {max_iterations} reached! Either something

Error message

Max iterations of {max_iterations} reached! Either something went wrong, or you can increase the max iterations with `.run(.., max_iterations=...)` or use `early_stopping_method='generate'` to generate a final response instead.

What it means

AgentWorkflow counts agent iterations per run; when num_iterations reaches max_iterations (default from workflow run config) it stops. With early_stopping_method='force' (the default) it raises WorkflowRuntimeError; with 'generate' it produces a best-effort final response via _generate_early_stopping_response instead.

Source

Thrown at llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py:543

        self, ctx: Context, ev: AgentOutput
    ) -> Union[StopEvent, AgentInput, ToolCall, None]:
        max_iterations = await ctx.store.get(
            "max_iterations", default=DEFAULT_MAX_ITERATIONS
        )
        num_iterations = await ctx.store.get("num_iterations", default=0)
        num_iterations += 1
        await ctx.store.set("num_iterations", num_iterations)

        if num_iterations >= max_iterations:
            early_stopping_method = await ctx.store.get(
                "early_stopping_method", default="force"
            )
            if early_stopping_method == "generate":
                return await self._generate_early_stopping_response(
                    ctx, ev, max_iterations
                )
            else:
                raise WorkflowRuntimeError(
                    f"Max iterations of {max_iterations} reached! Either something went wrong, or you can "
                    "increase the max iterations with `.run(.., max_iterations=...)` "
                    "or use `early_stopping_method='generate'` to generate a final response instead."
                )

        memory: BaseMemory = await ctx.store.get("memory")

        if ev.retry_messages:
            # Retry with the given messages to let the LLM fix potential errors
            history = await memory.aget()
            user_msg_str = await ctx.store.get("user_msg_str")
            agent_name: str = await ctx.store.get("current_agent_name")

            return AgentInput(
                input=[
                    *history,
                    ChatMessage(role="user", content=user_msg_str),
                    *ev.retry_messages,

View on GitHub (pinned to afd0fef371)

Solutions

Raise the budget: `await wf.run(user_msg=..., max_iterations=50)`.
Set early_stopping_method='generate' (in the AgentWorkflow constructor) so hitting the cap returns a generated final answer instead of raising.
Inspect the event stream / memory to find why the agent loops — usually a tool error the model keeps retrying or a handoff cycle.
Fix the misbehaving tool or prompt so the loop actually converges.

Example fix

# before
wf = AgentWorkflow(agents=[...], root_agent="researcher")
resp = await wf.run(user_msg="deep research task", max_iterations=10)  # raises

# after
wf = AgentWorkflow(
    agents=[...], root_agent="researcher",
    early_stopping_method="generate",
)
resp = await wf.run(user_msg="deep research task", max_iterations=50)

Defensive patterns

Strategy: fallback

Try / catch

from llama_index.core.workflow.errors import WorkflowRuntimeError

try:
    result = await wf.run(user_msg=q, max_iterations=50)
except WorkflowRuntimeError as e:
    if "Max iterations" in str(e):
        result = None  # graceful degradation: log partial progress from memory/events
    else:
        raise

Prevention

Size max_iterations to the task (tool-heavy research needs 30+).
Set early_stopping_method='generate' in production so the cap yields a response, not an exception.
Log the event stream during development to catch handoff/tool loops early.

When it happens

Trigger: A multi-step tool-calling loop that never terminates (agent keeps calling tools or handing off back and forth) and exceeds max_iterations; a too-low max_iterations for the task; passing max_iterations=5 to .run() on a task needing more steps with default early_stopping_method='force'.

Common situations: Handoff ping-pong between two agents; an LLM stuck re-calling a failing tool; reasoning-heavy tasks needing many iterations; tests with small iteration budgets.

Related errors

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/9499980631fbb7ee. Report an issue: GitHub.