Skip to main content

GraphRecursionError: How to Fix LangGraph's Recursion Limit

Updated for LangGraph 1.x. Tested on Python 3.11 and 3.12.

GraphRecursionError is the single most reported failure in LangGraph projects. It looks like a crash in the framework, and most developers treat it that way: they raise the limit, the error disappears, and then it comes back a week later on a different input. The limit itself is not the bug. It is the only place where LangGraph tells you that your graph kept looping without reaching a stop condition.

This tutorial covers what the error actually means, how the default limit changed across versions, and three fixes that hold up in production: breaking the cycle, raising the limit correctly, and routing out of the loop before the exception fires.

What the error looks like

The traceback ends with something close to this:

langgraph.errors.GraphRecursionError: Recursion limit of 25 reached without
hitting a stop condition. You can increase the limit by passing a higher
limit in the config argument at runtime.

The number in the message is your effective limit. If it says 25, your installed version predates the 10,000-step defaults introduced in the 1.0 line. If it says 10007, you are on a current 1.x release. Either way, the graph executed that many super-steps without reaching END.

Why it happens

LangGraph runs a graph in super-steps. Every super-step executes a set of nodes that share one round of message passing, then hands control to the next set of nodes chosen by the edges. The recursion limit counts super-steps, not individual node calls, so a graph with parallel branches consumes one step per round rather than one per node.

Two situations produce the error:

  • A real cycle. You wrote a → b and b → a, or a conditional edge whose condition never becomes false. The classic shape is an agent and a tool loop where the routing function checks the wrong field of state.
  • A legitimate deep graph. A long retry chain, a map-reduce over hundreds of documents, or a multi-agent conversation that genuinely needs thousands of steps. Nothing is wrong except the ceiling.

Diagnose before you patch. If you do not expect the graph to iterate, fixing the ceiling makes the bug quieter, not smaller. If the graph is supposed to iterate, raising the limit is the correct fix and nothing is broken.

Fix 1: break the cycle

The most common real cause is a conditional edge that never routes to END. Consider a research agent that keeps calling tools because it reads the message list from the wrong place, or a retry loop that compares a string against an enum.

Add a condition that is guaranteed to terminate, and make the exit explicit rather than implied:

from typing import Literal
from langgraph.graph import END, StateGraph

MAX_ATTEMPTS = 5

def should_continue(state: State) -> Literal["tools", "finish"]:
    if state["attempts"] >= MAX_ATTEMPTS:
        return "finish"
    if state.get("tool_calls"):
        return "tools"
    return "finish"

builder = StateGraph(State)
builder.add_node("agent", call_model)
builder.add_node("tools", run_tools)
builder.add_conditional_edges("agent", should_continue, {
    "tools": "tools",
    "finish": END,
})
builder.add_edge("tools", "agent")

Two details matter here. The counter lives in state and is incremented inside the node, so it survives checkpointing and resumes. And the routing function returns a named label mapped to a real node, which makes the exit visible in the graph definition instead of hidden inside a truthiness check.

If your graph has a cycle you want to keep, put a hard stop in the state anyway. A loop with an explicit attempt budget fails fast and consistently, which is far easier to debug than a loop that only fails when the model happens to behave badly.

Fix 2: raise the limit the right way

When the depth is legitimate, raise the limit at invoke time. The value belongs at the top level of the config object:

graph.invoke(
    {"messages": [{"role": "user", "content": "Summarize this repo"}]},
    {"recursion_limit": 200},
)

Putting recursion_limit under configurable is the mistake that follows. configurable holds values your nodes and tools can read, and the runtime ignores it for execution control:

# Wrong: the runtime never reads this key
graph.invoke(inputs, {"configurable": {"recursion_limit": 200}})

# Right: top-level config key
graph.invoke(inputs, {"recursion_limit": 200})

To change the ceiling everywhere without editing every call site, set the environment variable. In LangGraph 1.1.4 and later the default is 10,007 super-steps, and LANGGRAPH_DEFAULT_RECURSION_LIMIT overrides it:

export LANGGRAPH_DEFAULT_RECURSION_LIMIT=500
python app.py

Version history is worth keeping in mind when you read older advice. The 1.0.6 to 1.1.3 defaults sat at 10,000 steps. Anything earlier used a limit of 25, which is where most of the "just bump it to 1000" advice on forums comes from. If your traceback mentions 25 and your project is on a modern release, check for a pinned old langgraph version in the lockfile before changing any code.

Fix 3: exit the loop before the exception

Raising the limit converts a crash into a longer run, not into a good answer. When the graph is doing open-ended reasoning, give it a completion path and route into it while there is still budget left.

The RemainingSteps managed value exposes the countdown as part of state, so a conditional edge can send the run to a wrap-up node instead of dying:

import operator
from typing import Annotated
from typing_extensions import TypedDict

from langgraph.graph import END, START, StateGraph
from langgraph.managed.is_last_step import RemainingSteps

class State(TypedDict):
    messages: Annotated[list, operator.add]
    remaining_steps: RemainingSteps

def route(state: State) -> str:
    return "fallback" if state["remaining_steps"] <= 2 else "reason"

builder = StateGraph(State)
builder.add_node("reason", reason_node)
builder.add_node("fallback", best_effort_node)
builder.add_edge(START, "reason")
builder.add_conditional_edges("reason", route, {
    "reason": "reason",
    "fallback": "fallback",
})
builder.add_edge("fallback", END)
graph = builder.compile()

graph.invoke({"messages": []}, {"recursion_limit": 10})

If you would rather keep the graph untouched, catch the exception outside and return a degraded response. Nodes can also read the current step from run metadata, which is handy for logging how close a run came to the ceiling:

from langchain_core.runnables import RunnableConfig
from langgraph.errors import GraphRecursionError

def my_node(state: dict, config: RunnableConfig) -> dict:
    step = config["metadata"]["langgraph_step"]
    return {"last_step": step}

try:
    graph.invoke(inputs, {"recursion_limit": 50})
except GraphRecursionError:
    result = {"error": "run exceeded its step budget"}

The two approaches answer different questions. RemainingSteps keeps the run alive and produces output, which suits user-facing agents. Catching GraphRecursionError stops the run and reports, which suits batch jobs where a partial answer is worse than a clean failure. Picking one deliberately is the difference between a graph that degrades and a graph that retries forever.

Checking the fix

Instrument the routing function first. Log the attempt counter, the pending tool calls, and the step number for every decision, then run the input that failed. If the counter never increases, your state update is being dropped, usually because the node returns a new dict instead of an update or because a reducer overwrites the field. If the counter increases but the route never changes, the bug is in the condition, not in the graph.

Only after the routing logic is proven correct should the recursion limit be raised, and then only to a value you can justify against the longest legitimate run you expect.

We use cookies for ads and analytics.