If your n8n workflow just died with Agent stopped because maximum number of iterations has been reached, the agent didn't crash and your credentials are fine. The AI Agent node runs a reasoning loop — read the request, pick a tool, read the result, decide what's next — and the Tools Agent stops that loop after 10 passes by default, so the error means the model kept choosing tool calls instead of writing a final answer. Roughly nine times out of ten the cause is tool selection, not the limit: two tools the model can't tell apart, or a tool description that never tells it when to stop. Raising Max Iterations on a looping agent doesn't fix it. It just makes the same failure cost more.
We maintain a few dozen production n8n agents for clients, and this is the error we get asked about more than any other. The frustrating part is that the fix people reach for first — bump the number — is the one that reliably makes things worse.
What an iteration actually is
The agent loop is simpler than it looks. n8n sends the model your system message, the user input, and the description of every tool attached to the node. The model replies with either a final answer or a tool call. If it's a tool call, n8n executes the sub-node, appends the result to the conversation, and sends the whole thing back. That round trip is one iteration.
Two things follow from that, and both matter.
First, iterations are not steps in your workflow, they're decisions by the model. A failed tool call still costs an iteration. So does a tool that returns an empty array. An agent with three tools can burn ten iterations without accomplishing anything.
Second, every iteration re-sends the entire accumulated context plus all your tool descriptions. Iteration nine is dramatically more expensive than iteration one. This is why a looping agent shows up on your Anthropic or OpenAI bill before it shows up in a client complaint — the pattern is the same one we covered in cutting Claude API costs, where the token count grows quadratically while the work done stays flat.
The Max Iterations option lives under Options on the Tools Agent node and, per the n8n docs, it "defaults to 10." It isn't visible until you add it, which is why plenty of people hit the error without ever knowing the setting exists.
First: is your agent looping or just busy?
These are opposite problems with opposite fixes, and you cannot tell them apart from the error message. Turn on Return Intermediate Steps in the node options and run it again.
A busy agent shows ten distinct tool calls with different inputs, each one advancing toward the answer — search, then fetch, then look up, then check, then write. It ran out of room. Raise the limit to 15 or 20 and you're done. This is the honest minority case, and it's common in research agents and anything doing pagination.
A looping agent shows the same tool called repeatedly with near-identical arguments, or two tools alternating. It isn't making progress, and no limit will help. Every extra iteration you grant it is money spent on the same wrong decision.
If you already have proper observability on your n8n agents, you can skip the intermediate-steps toggle and read the trace directly — a Langfuse trace shows the loop shape at a glance, including which tool descriptions were in context when the model made the bad call.
The three causes we actually find
Too many tools in one reasoning context
This is the big one. Every tool description goes into the prompt on every iteration, and the longer that candidate list gets, the worse the model chooses from it. Research on tool selection backs this up directly: showing an agent a shorter, query-relevant tool list rather than a fixed one lifted Claude Sonnet's selection accuracy from 87.1% to 93.1%. Fewer candidates in context, better picks — and a bad pick is where the loop starts.
In our own workflows the practical ceiling sits around eight to ten tools per agent before we start seeing repeat calls. That's a heuristic, not a law, and it moves with how well the descriptions are written.
Community reports on n8n specifically are harsher — multiple users have found that going past two or three tools is enough to trigger loops, regardless of whether the tools are HTTP Request nodes, sub-workflows, or Code nodes. That's not a contradiction of the benchmarks so much as a reminder that description quality matters more than count.
The fix isn't fewer capabilities, it's fewer capabilities per agent. Split the work: a router agent that classifies the request, then a specialist agent per category with three or four tools each. We covered the structural version of this decision in AI Agent node vs sub-workflow, and the token math usually favors splitting anyway, because a specialist agent carries a much smaller prompt.
Tool descriptions that don't say when not to use the tool
Most descriptions are written as documentation for humans. The model doesn't need documentation — it needs selection criteria.
Compare these:
- Weak:
Handles customer data.The model has no idea whether a refund request, an address change, or an order status question belongs here. It'll try, get something unhelpful, and try the next tool. - Better:
Looks up a single customer order by order ID or email address.Now the trigger is clear, but the model still doesn't know what a miss looks like. - Right:
Looks up a single customer order by order ID or email address. Returns an empty result if no order exists — that is a valid answer, not a failure. Do not use for refunds, cancellations, or address changes.
That last clause is what breaks loops. An agent retries because it interpreted an empty result as a failed attempt. Tell it explicitly that empty means "no", and the retry never happens.
No stop condition in the system message
The system message is where you tell the agent what "done" means. Without it, models trend toward trying harder rather than reporting a null result — a bias that produces exactly the behavior we see in n8n loops.
Two lines fix most of it:
If a tool returns no results, report that to the user. Do not call another tool to double-check.Call each tool at most once per request unless the user asks for more.
Blunt, and it works. It's the same principle behind testing agents before they reach production: agents don't fail because they lack ability, they fail because nobody defined the boundaries.
The gotcha: the error output may not fire
Here's the one that catches teams who did everything else right. There's an open n8n issue reporting that when the AI Agent node hits Max Iterations with On Error set to Continue, execution routes to the success output instead of the error output. It's labelled for the AI team and tracked internally.
Practically: your carefully built error branch never fires, and a truncated agent response flows downstream as if it were a complete answer. On a client-facing workflow, that's a partial reply landing in someone's inbox.
Don't rely on the branch. Put an IF node immediately after the agent that validates the output is a real answer — non-empty, and not the max-iterations string — and route the failures into your error path yourself. If you don't have one of those yet, error handling and monitoring for n8n is the piece to build before you build another agent.
Where to set Max Iterations once you've fixed the cause
Once the loop is gone, treat the limit as a cost circuit breaker rather than a capacity setting. Count the tool calls a correct run genuinely needs, multiply by about 1.5, and set it there.
An agent that should make three calls gets 5, not 30. When something regresses — a tool starts returning empty, a model update changes selection behavior — it fails after 5 wasted calls instead of 30. On a workflow firing a few thousand times a month, that difference is real money.
Two things that also help, both worth setting up regardless:
- Keep memory scoped. An agent carrying a long conversation into every iteration is paying the loop tax twice. Getting n8n agent memory right directly reduces per-iteration cost.
- Alert on iteration count, not just failures. An agent quietly averaging 8 of 10 iterations is one model update away from breaking, and nothing in your error log says so today.
The short version
The error is a symptom. The disease is almost always that your agent can't tell which tool answers the question, or doesn't know it's allowed to stop.
Read the intermediate steps first. If the agent is repeating itself, cut the tool count, rewrite descriptions to include what the tool doesn't do, and add an explicit stop condition. If it's genuinely doing more work than 10 iterations allow, raise the limit and move on. Either way, validate the output with an IF node rather than trusting the error branch, because that branch may not fire.
If you've got agents in production that you're not fully confident in — looping, silently truncating, or just costing more than they should — that's exactly what we look at in a free automation audit. We'll go through your workflows, find the loops and the silent failures, and tell you what to fix first. No pitch required.