max_iter exceeded
crewai.agents.agent.Agent max iteration limit exceeded
Stack trace
CrewAI Agent Execution Error: Agent 'research_agent' exceeded max_iter limit of 15 iterations without completing task 'research_market_trends'. Last action: tool_use (google_search) Last observation: Search returned 2,847 results, but agent did not converge on final answer. Task status: INCOMPLETE To increase iterations, set agent.max_iter=30 or higher.
Why it happens
CrewAI agents use a planning loop where each iteration consists of thinking, tool use, and observation. By default, agents have a max_iter limit of 15 to prevent infinite loops and excessive API costs. When an agent's task is complex, poorly defined, or the tools don't provide enough information to reach a confident answer, the agent cycles through iterations without converging. This is especially common with open-ended research tasks, ambiguous requirements, or when tool responses don't directly answer the question.
Detection
Monitor agent execution logs for 'iteration X of max_iter' messages. Implement callbacks on agent.on_iteration_end() to track whether the agent is making progress toward the task goal or looping on the same actions. Log the LLM's internal reasoning to spot if it's stuck in a reasoning loop rather than moving toward closure.
Causes & fixes
Task goal is too vague or open-ended without clear success criteria
Rewrite the task description with explicit, measurable success criteria. Example: Instead of 'research AI trends', use 'Find the top 3 AI breakthroughs in 2025 with dates and impact summaries (max 50 words each)'
max_iter is set too low for the task complexity (default 15 is insufficient)
Increase max_iter when creating the Agent: agent = Agent(role='researcher', goal='...', max_iter=30, tools=[...]). Adjust based on task complexity: simple tasks 15-20, complex research 30-50, multi-step workflows 50-100.
Tools are not returning actionable information or are returning ambiguous/incomplete data
Improve tool integration: add tool descriptions that explain expected output format, implement tool result validation to ensure data quality, or add a summary tool that consolidates findings. Example: Add a 'summarize_findings' tool that takes raw search results and returns a structured answer.
Agent is looping on the same tool/action without trying alternatives or converging
Add tool_choice constraints or implement a tool diversity check: use agent callbacks to track tool usage and force the agent to try different tools if it repeats the same tool more than 2x. Or, add a 'decision_gate' tool that forces the agent to commit to an answer after gathering minimum evidence.
Code: broken vs fixed
from crewai import Agent, Task, Crew, Process
import os
# BROKEN: max_iter is too low, task goal is vague
research_agent = Agent(
role="Market Research Analyst",
goal="Research market trends", # ← Too vague, no clear success criteria
tools=[google_search_tool, web_scraper_tool],
verbose=True
# ← max_iter not set, defaults to 15 — not enough for open research
)
research_task = Task(
description="Look into the latest AI market trends and report back", # ← Vague, no specifics
agent=research_agent,
expected_output="Market trends report"
)
crew = Crew(
agents=[research_agent],
tasks=[research_task],
process=Process.sequential,
verbose=True
)
# This will hit max_iter exceeded because goal is vague and iterations are low
result = crew.kickoff()from crewai import Agent, Task, Crew, Process
import os
# FIXED: Clear goal + higher max_iter + specific success criteria
research_agent = Agent(
role="Market Research Analyst",
goal="Identify the top 3 AI market trends in 2025 with quantified impact data", # ← Specific, measurable
tools=[google_search_tool, web_scraper_tool, summarize_findings_tool], # ← Added summary tool
max_iter=35, # ← Increased from default 15 to 35 for research depth
verbose=True
)
research_task = Task(
description="Find the 3 most significant AI trends in 2025. For each trend: name, one-sentence description, market size impact (if available), and 2 key citations. Prioritize recent data from the last 3 months.", # ← Explicit, measurable
agent=research_agent,
expected_output="""Structured report:
1. Trend Name: [X]
Description: [max 1 sentence]
Market Impact: [quantified or 'Not available']
Citations: [2 sources with dates]
2. Trend Name: [Y]
...
3. Trend Name: [Z]
..."""
)
crew = Crew(
agents=[research_agent],
tasks=[research_task],
process=Process.sequential,
verbose=True
)
try:
result = crew.kickoff()
print(f"Task completed successfully:\n{result}")
except Exception as e:
if "max_iter" in str(e):
print(f"Agent exceeded iteration limit. Increase max_iter further or simplify task goal.")
raiseWorkaround
If you can't refactor the task immediately, catch the max_iter exception and use a two-phase approach: run the agent with current max_iter, capture the last observations/reasoning from logs, then manually synthesize a partial answer from the agent's intermediate findings. Alternatively, break the large task into 3-4 smaller, highly specific subtasks, each with lower max_iter (15-20) and explicit success criteria, then have a coordinator agent combine the results.
Prevention
Adopt a 'constraint-first' design pattern: before creating an Agent/Task, define measurable success criteria and estimate iterations needed (simple tasks ~10-15, moderate ~20-30, complex ~40-60). Use CrewAI's built-in logging and callbacks to monitor iteration count and tool usage patterns in staging. Implement a tool diversity metric that flags if the same tool is called >3 times in a row. Create a 'decision checkpoint' tool that forces the agent to commit to an answer once minimum evidence is gathered, preventing endless refinement loops.