{"record":{"id":"9499980631fbb7ee","repo":"run-llama/llama_index","slug":"max-iterations-of-max-iterations-reached-either-949998","errorCode":null,"errorMessage":"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.","messagePattern":"Max iterations of (.+?) 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\\.","errorType":"exception","errorClass":"WorkflowRuntimeError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py","lineNumber":543,"sourceCode":"        self, ctx: Context, ev: AgentOutput\n    ) -> Union[StopEvent, AgentInput, ToolCall, None]:\n        max_iterations = await ctx.store.get(\n            \"max_iterations\", default=DEFAULT_MAX_ITERATIONS\n        )\n        num_iterations = await ctx.store.get(\"num_iterations\", default=0)\n        num_iterations += 1\n        await ctx.store.set(\"num_iterations\", num_iterations)\n\n        if num_iterations >= max_iterations:\n            early_stopping_method = await ctx.store.get(\n                \"early_stopping_method\", default=\"force\"\n            )\n            if early_stopping_method == \"generate\":\n                return await self._generate_early_stopping_response(\n                    ctx, ev, max_iterations\n                )\n            else:\n                raise WorkflowRuntimeError(\n                    f\"Max iterations of {max_iterations} reached! Either something went wrong, or you can \"\n                    \"increase the max iterations with `.run(.., max_iterations=...)` \"\n                    \"or use `early_stopping_method='generate'` to generate a final response instead.\"\n                )\n\n        memory: BaseMemory = await ctx.store.get(\"memory\")\n\n        if ev.retry_messages:\n            # Retry with the given messages to let the LLM fix potential errors\n            history = await memory.aget()\n            user_msg_str = await ctx.store.get(\"user_msg_str\")\n            agent_name: str = await ctx.store.get(\"current_agent_name\")\n\n            return AgentInput(\n                input=[\n                    *history,\n                    ChatMessage(role=\"user\", content=user_msg_str),\n                    *ev.retry_messages,","sourceCodeStart":525,"sourceCodeEnd":561,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py#L525-L561","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","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."],"exampleFix":"# before\nwf = AgentWorkflow(agents=[...], root_agent=\"researcher\")\nresp = await wf.run(user_msg=\"deep research task\", max_iterations=10)  # raises\n\n# after\nwf = AgentWorkflow(\n    agents=[...], root_agent=\"researcher\",\n    early_stopping_method=\"generate\",\n)\nresp = await wf.run(user_msg=\"deep research task\", max_iterations=50)","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"from llama_index.core.workflow.errors import WorkflowRuntimeError\n\ntry:\n    result = await wf.run(user_msg=q, max_iterations=50)\nexcept WorkflowRuntimeError as e:\n    if \"Max iterations\" in str(e):\n        result = None  # graceful degradation: log partial progress from memory/events\n    else:\n        raise","preventionTips":["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."],"tags":["agent-workflow","loop-guard","max-iterations","runtime"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}