Fix n8n agent stopped due to max iterations error

Running into the dreaded "n8n agent stopped due to max iterations" error can be frustrating, especially when your workflow was running smoothly just moments before. This error occurs when an n8n workflow agent hits a predefined execution limit, preventing potential infinite loops or runaway processes. While this built-in safeguard is crucial, it can sometimes get in the way of legitimate workflows that naturally require more steps. In this guide, you'll discover what causes this error, how to fix it, and best practices to avoid it in the future.

What Does "n8n Agent Stopped Due to Max Iterations" Actually Mean?

This error is tied to the execution loop limit that n8n uses to protect your system from infinite processes. When a workflow or agent performs the same step too many times — typically 100 by default — the n8n engine automatically shuts it down with the message:

“Agent stopped because maximum number of iterations has been reached.”

This limit is especially relevant in agent-style workflows (like AI agents using tools such as CrewAI or LangChain) where loops are part of the process. If your agent uses logic that relies on repeatedly evaluating or calling external tools, the max iterations threshold can be hit quite fast.

Common Use Cases That Trigger This Error

Here are a few examples where the n8n agent stopped due to max iterations error often shows up:

• LLM-powered agents stuck in internal loops (e.g., re-thinking responses)
• Web scraping agents navigating through paginated content
• Recursive workflows using the Execute Workflow node or similar logic
• Multi-agent orchestration with back-and-forth loops like those created using CrewAI

If you're building LLM agents in n8n with CrewAI, this is particularly common, as agents regularly interact with multiple tools and memory chains.

How to Fix the n8n Max Iterations Error

You can resolve this error in two primary ways:

1. Increase the Max Iteration Limit

If your agent is functioning as expected and the loop isn’t a bug, you can simply raise the allowed number of iterations.

🔧 Steps to Increase Max Iteration Limit in n8n

1. Locate your environment file (e.g., .env for Docker or self-hosted installs).

2. Add or modify the setting:

   N8N_AGENT_MAX_LOOP_ITERATIONS=500
   

   Tip: 500 is an example; choose a value according to your workflow's needs.

3. Restart n8n for the update to take effect.

For Docker users, this means re-running your container using docker-compose or your preferred method. If you're using Portainer to manage Docker deploys, simply edit the environment variable from the UI.

2. Optimize Your Workflow Logic

Before increasing the iteration cap, review your agent’s design. Sometimes the issue lies in inefficient or flawed logic.

✅ Optimization Checklist

• Avoid unnecessary recursion in the Execute Workflow node.
• Break loops with a Switch or If node once a goal is reached.
• Use step counters by storing values in variables to check loop depth.
• Implement memory awareness inside LLM tools — especially when chaining multiple agents.

You can even log the number of iterations by creating a custom counter using the Set and Function nodes. This way, you can track what step each iteration is on and debug accordingly.

Real Example: Fixing an AI Agent Loop Limit

Let’s say you’re using CrewAI inside n8n to control multiple agents that receive tasks from a main controller. The controller agent loops through a TaskResolver until a task is marked "complete".

Agent: Task 1 received
Loop: Processing Task 1
Loop: Still processing...
Loop: Still not done...
...
n8n Agent Stopped: Max iterations reached

Solution:

• Add a simple Switch node to check whether task.status == 'done' and only continue if it’s still in progress.
• Log each step into a local variable to manually review how many loops are needed.
• Finally, bump N8N_AGENT_MAX_LOOP_ITERATIONS=300 to adjust for longer agents that are behaving correctly.

This balance gives you both safety and flexibility.

Where to Set This on Cloud or Hosted Platforms

If you're using n8n Cloud, the ability to modify environment variables may be limited. You can:

• Contact support to request an increase in the loop limit.
• Rebuild the workflow to reduce unnecessary iterations or split the task into smaller workflows.

For full flexibility and control over such system settings, self-hosting n8n is often the best long-term solution.

---

Table: Max Iterations Fix Options

Here’s a visual comparison of your available choices:

Approach	Use When	Level of Control
Increase loop count via .env	Your workflow needs more steps and isn’t looping endlessly	High
Redesign workflow logic	The agent behavior is inefficient or stuck in recursion	Very High
Add switch/stop conditions	You want to halt the loop once a task or condition is met	High
Use counters/logging	You need better visibility into how many loops are occurring	Medium
Switch to self-hosted deployment	You need full environment customization	Full

---

Tips to Avoid the Error in the Future

• Design modular workflows: Instead of one large loop, split complex workflows into smaller ones.
• Throttle LLM interactions: If you’re using GPT-based tools within n8n, include delays or conditional use.
• Monitor total iterations: Use internal Set or Function nodes to count how many loops your agent is performing.
• Set alerts on loop errors: With nodes like Slack or email, notify yourself when agents fail due to loop limits.

For enhanced error handling, check out this guide to error catching in n8n.

Final Thoughts

Hitting the "n8n agent stopped due to max iterations" error may feel like a limitation, but it’s actually a helpful safety net. By increasing the limit responsibly and improving how your workflows handle iterations, you gain more stability and predictability — especially for AI agent use cases. Whether you're using no-code tools or embedding LLM agents, staying within iteration thresholds is part of smart automation design.

And if you’re just getting started or considering switching platforms, you can try n8n for free with this link and explore self-hosted or cloud deployments to match your flexibility needs.

---

FAQ

What is the default max iteration limit in n8n?

By default, the max iteration limit is set to 100. If a workflow exceeds this during execution, n8n will stop the agent and throw the iteration error.

Can I completely disable the iteration limit?

Disabling the limit entirely is not recommended, and there's no supported way to set it to “infinite.” However, you can set a very large number, like 10000, within reason.

Does changing iterations affect performance?

Yes, increasing the max iteration limit can consume more memory and CPU. Monitor your system closely and ensure your workflows are efficient.

Why do AI workflows hit iteration limits so easily?

AI agents, especially in multi-step tasks or recursive goal-setting, naturally require more steps than standard workflows. Every tool call, memory fetch, or task pulse can be an iteration.

Is this error the same on n8n Cloud?

Yes, the logic is the same, but on n8n Cloud, you may need to contact support to increase the iteration cap since direct environment access is restricted.

If you’re heavily using AI tools like CrewAI or LangChain with n8n, consider comparing automation platforms to choose one that scales with your complexity.