Max iterations reached

Agent stopped: reached MAX_AGENT_ITERATIONS (40). The task may be too complex
for a single run, or the agent is stuck.

InsightWorker caps each run at 40 LLM↔tool round trips by default. Hitting the cap means one of:

1. Task is genuinely large — needs more iterations
2. Agent is stuck — same path being retried with no progress
3. Tool returning slowly — agent taking many small steps when one big step would work

Diagnose first, raise second

Before raising MAX_AGENT_ITERATIONS, look at the session transcript to see why it took 40 steps.

ls -lt ~/.insightworker/sessions/ | head
# Open the most recent .jsonl and skim

Patterns to look for:

Raise the cap

If you've confirmed the task is just large, raise the cap:

# ~/.insightworker/.env
MAX_AGENT_ITERATIONS=80

For very large apps (full code migrations, multi-day digests), 100-150 is reasonable. Above 200, consider breaking into multiple skills chained via the daemon.

Break the task into smaller steps

The cleanest fix for a complex run is to split it. Two patterns:

Skill chaining

Define skills that each handle one phase, and have the user invoke them in sequence:

insightworker skill run gather-data
insightworker skill run analyze
insightworker skill run write-report

Plan-then-execute

Have the first run produce a plan file; the second run executes it:

# Run 1: produces /tmp/plan.json
insightworker "Plan the migration of foo to bar; output JSON to /tmp/plan.json"

# Run 2: executes the plan
insightworker "Execute the plan in /tmp/plan.json step by step"

Each run starts fresh with full iteration budget.

See also

• permissions-and-safety/loop-detector.md — loop detection (the related guard)
• tool-failures.md — fixing the errors that drive runaway iterations
• extending/skills.md — define multi-step apps

Source: docs/troubleshooting/max-iterations.md in the public repo. Open a PR with corrections.