"Agent stopped due to iteration limit"? What that message really means — and the fix

The run ends. The message reads "Agent stopped due to iteration limit or time limit" (or a LangGraph recursion limit, or your own step_limit). No result, no obvious error. The instinct is to raise the limit — but that cap firing is a symptom, and raising it usually just moves the wall further out.

What the message actually tells you

A step/iteration cap is a framework default deciding when your run ends. When the agent only ever stops at the cap, that's a run whose ending was never specified — a design gap, not a prompting mistake. The cap did its job (it stopped an unbounded run); it just can't tell you why the run was unbounded.

In the large majority of cases, the real cause is one of two things:

• A loop. The agent repeats a (tool, args) step and never treats any result as final, so it never converges before the cap. This is the most common cause.
• A missing stop condition. Nothing in the run defines "done," so the agent keeps working past the point of progress until the cap catches it.

Find the real reason

Don't guess — read the run as a sequence of steps and look for a repeating fingerprint. Snapback's diagnose_trace does this for you: send the trace and it returns the actual failure class (often loop_repeated_tool_call), the root cause, and the fix — so you fix the cause, not the cap:

diagnose_trace({trace: { final_status: "failed", steps: [
  /* ...your run's steps... */,
  {action:"step_limit", error:"stopped due to iteration limit", status:"failed"} ]}})

// → { failure_class: "loop_repeated_tool_call",
//      root_cause: "agent repeated web_search without a stop condition",
//      fix_suggestion, confidence }

The fix

1. Add an explicit stop condition — define "done" so the agent stops on success, not on the cap.
2. Add no-progress detection — if a step's (tool, args) fingerprint repeats, cut or escalate rather than retry.
3. Make tool results unambiguous — a clear status: "ok" vs "no_results" vs "error" lets the model decide it's finished, which prevents the loop that fills the cap.
4. Only then, tune the cap — raise it if the task legitimately needs more steps; lower it as a tighter backstop otherwise.