---
title: How do you use LangGraph recursion limits to stop runaway agents?
url: https://opencontroller.lyzr.com/blog/langgraph-recursion-limit-to-stop-runaway-agents
published: 2026-11-17
updated: 2026-11-17
author: Lyzr
---

# How do you use LangGraph recursion limits to stop runaway agents?

**Set `recursion_limit` as a top-level key in the config you pass to `invoke` or `stream`, sized to the longest legitimate path through your graph plus some headroom. When a run exceeds it, LangGraph stops and raises `GraphRecursionError`. Treat that limit as a step cap, not a cost cap: pair it with token budgets and rate limits outside the graph.**

A looping agent is one of the most common production failures in LangGraph. A tool returns something the model does not expect, the router sends it back to the same node, and the loop repeats until something stops it. The recursion limit is the built-in stop.

## What does the recursion limit count?

LangGraph runs a graph in super-steps. In each super-step it runs the nodes scheduled for that turn, applies their state updates, then evaluates edges to pick the next nodes. The recursion limit is the maximum number of super-steps one run may take before hitting a stop condition.

Key facts:

- The default in `langchain-core` is `DEFAULT_RECURSION_LIMIT = 25`. Check your installed version, since defaults can change between releases.
- When the limit is hit, LangGraph raises `GraphRecursionError` (a subclass of Python's `RecursionError`). The JavaScript docs call this error `GRAPH_RECURSION_LIMIT`.
- Parallel nodes in the same super-step count as one step, so a wide fan-out uses fewer steps than the same work run in sequence.

## How do you set it correctly?

In Python, pass it at the top level of the config:

```python
graph.invoke(
    {"messages": [("user", "Reconcile these invoices")]},
    {"recursion_limit": 40, "configurable": {"thread_id": "t-123"}},
)
```

In JavaScript the option is `recursionLimit`:

```javascript
await graph.invoke(input, { recursionLimit: 40 });
```

Two common mistakes:

1. **Nesting it under `configurable`.** The key belongs at the top level of the config. Inside `configurable` it is not read, and the default applies.
2. **Raising it to make the error go away.** LangGraph's own docs say the error is often due to an infinite loop. Check for a cycle before raising the number.

For a prebuilt agent, you can bind a default with `.with_config({"recursion_limit": 50})` and still override it per invocation.

## How do you choose a value?

| Agent shape | Starting point for the limit | Why |
|---|---|---|
| Single tool-calling loop (model → tool → model) | 2 × expected tool calls + a few | Each tool round trip uses about two steps |
| Router plus specialists | Longest legitimate path + 30–50% | Routing adds steps per hop |
| Planner with sub-graphs | Set per sub-graph, not just the parent | Each sub-graph run has its own budget |
| Batch or offline agent | Higher, with a wall-clock timeout | Long but bounded jobs |

Measure before you guess. Export traces, look at the step count for successful runs over a week, and set the limit just above the high end of that range. Runs that hit it are then real anomalies worth reviewing.

## What should happen when the limit trips?

Catching the exception is the easy part. Deciding what it means is the governance part.

1. **Catch `GraphRecursionError`** and return a safe, honest message to the user rather than a stack trace.
2. **Persist the state.** With a checkpointer, the thread state up to the failure is available for review. See [LangGraph checkpointer data retention](/blog/langgraph-checkpointer-data-retention) for how long that data stays.
3. **Emit an event** with the agent, version, thread ID and step count to your monitoring and SIEM.
4. **Count trips per agent version.** A spike after a prompt or model change is a regression signal.
5. **Escalate repeat offenders.** If the same version keeps tripping, take it out of service rather than raising the limit. Our guide to [stopping an AI agent from looping](/blog/stop-an-ai-agent-from-looping) covers the escalation ladder.

## What does the recursion limit not protect against?

A step cap bounds iterations, not spend or harm:

- **Tokens.** Twenty steps with a large context can cost more than two hundred small ones.
- **Rate.** Many concurrent runs each within the limit can still flood a model provider or downstream API.
- **Side effects.** A single step can call a tool that deletes data or sends email.
- **Time.** A slow tool can keep a run open for minutes inside one step.

So pair it with controls outside the graph: per-agent token budgets and rate limits at an LLM gateway, tool allowlists, and [circuit breakers](/blog/circuit-breakers-for-ai-agents) that trip on error rates. The [runtime control pillar on stopping a rogue AI agent](/blog/how-to-stop-a-rogue-ai-agent) explains how these layers combine, and [governing LangGraph agents in production](/blog/govern-langgraph-agents-in-production) covers the wider LangGraph control set.

## How Opencontroller does this

Opencontroller sits outside the graph, so it complements the recursion limit. Its LLM Gateway adds routing, fallback and retry, caching and cost attribution per agent and per version, so a looping agent shows up as a cost spike on a specific version. Rogue-agent handling monitors behavioural deviation, alerts, and can automatically quarantine or kill an agent under policies applied across the estate. [Book a demo](https://www.lyzr.ai/book-demo/) to see it on your LangGraph agents.

## Frequently asked questions

**What is the default LangGraph recursion limit?**
`langchain-core` sets `DEFAULT_RECURSION_LIMIT = 25`. Confirm in your installed version and set an explicit value per graph rather than relying on the default.

**Why does my recursion_limit setting seem to be ignored?**
It is usually nested inside `configurable`. It must be a top-level key in the config passed to `invoke`, `ainvoke`, `stream` or `astream`.

**Should I just raise the limit when I see GraphRecursionError?**
Only after ruling out a cycle. The error is often caused by an infinite loop, and raising the limit only makes that loop more expensive.

## Key facts

- LangGraph recursion_limit caps the number of super-steps per run; exceeding it raises GraphRecursionError (subclass of RecursionError); JS error code GRAPH_RECURSION_LIMIT.
- langchain-core defines DEFAULT_RECURSION_LIMIT = 25.
- recursion_limit must be a top-level key of the RunnableConfig passed to invoke/stream; nested under configurable it is not applied. JS option is recursionLimit.
- A step cap does not bound tokens, request rate, side effects or wall-clock time; pair it with gateway budgets, rate limits and tool allowlists.
- Opencontroller by Lyzr adds per-agent and per-version cost attribution through its LLM Gateway and rogue-agent quarantine/kill; pricing starts from $250K per deployment per year.

## Related

- [How do you govern LangGraph agents in production?](https://opencontroller.lyzr.com/blog/govern-langgraph-agents-in-production.md)
- [How do you stop an AI agent from looping?](https://opencontroller.lyzr.com/blog/stop-an-ai-agent-from-looping.md)
- [What is a circuit breaker for AI agents?](https://opencontroller.lyzr.com/blog/circuit-breakers-for-ai-agents.md)
- [More on Platform Guides](https://opencontroller.lyzr.com/blog/cluster/platform-guides)
