langgraph GraphRecursionError: how to raise recursion_limit and debug cycles

TL;DR

GraphRecursionError means your LangGraph run hit the step cap (default 25 supersteps) without terminating. If the loop is legitimate work that just needs more steps, pass a higher recursion_limit in the run config: graph.invoke(state, {"recursion_limit": 100}). If the graph was supposed to finish already, the limit is doing its job, do not raise it, fix the loop instead.

The error

graphrecursionerror: Graph has reached the maximum number of supersteps (25)

When to use this skill

• graph.invoke(), graph.stream(), or graph.ainvoke() raises GraphRecursionError from langgraph.errors.
• You see the limit message at 25 supersteps (or whatever value you set).

When NOT to use this skill

• Your graph hangs forever with no error. That is not the recursion limit; look for a blocking node, a deadlock in a shared resource, or a loop with no termination check that never reaches the cap because one step never returns.
• You want to remove the limit entirely. The limit is the only thing that keeps a bad cycle from burning through your API budget.

Fix it: raise the limit for legitimately long runs

1. Import the error so you can catch it.

   from langgraph.errors import GraphRecursionError

Expected: the import succeeds. If it fails, you are on an old langgraph release; upgrade with pip install -U langgraph.

1. Pass a higher limit in the run config.

   result = graph.invoke(inputs, {"recursion_limit": 100})

Expected: the run completes and returns the final state. The default of 25 is too low for agent loops with tool calls; a ReAct agent that calls 3 tools per reasoning round burns ~6 supersteps per round, so 25 gives it about 4 rounds.

1. Set the limit per run, not globally. Keep small limits on simple graphs so cycles fail fast:

   RESEARCH_RUN_CONFIG = {"recursion_limit": 100}  # deep agent loops
   QA_RUN_CONFIG = {"recursion_limit": 15}          # simple Q and A, catches cycles fast

Expected: simple flows still crash loudly on a cycle instead of grinding to the higher ceiling.

1. Catch the error and return partial results instead of crashing.

   try:
       result = graph.invoke(inputs, {"recursion_limit": 100})
   except GraphRecursionError:
       logger.error("recursion limit hit; returning partial state")
       result = last_known_state

Expected: a runaway loop surfaces as a logged, recoverable event instead of a 500.

1. If the graph STILL hits the new limit, the loop is a bug. Find the cycle:

• Enable tracing (LangSmith or debug=True in streaming) and watch which nodes repeat.
• Check every conditional edge for a path back to a node you already visited. The usual bug is a router whose exit condition never becomes true (for example, an LLM node that always returns a tool call because the tool result is malformed).
• Add a real exit condition to the router: route to END when attempts >= MAX_ATTEMPTS or when the state holds a valid answer.
• Give the graph its own loop counter separate from the recursion limit: your own counter is the intended exit, the recursion limit is the backstop.

Variant phrasings

GraphRecursionError: maximum recursion depth exceeded in a langgraph tool loop

Same error, raised from a tool-calling agent. Fix: raise recursion_limit in the invoke config AND check that the tool actually succeeds. A tool that always errors back makes the LLM retry forever; the fix there is tool repair, not a higher limit.

Recursion error in a compiled subgraph

Subgraphs share the parent's limit by default. Raise the limit on the outer invoke, or simplify: subgraphs that loop internally should expose their own explicit MAX_STEPS so a parent-level cap of 25 does not kill legitimate nested work.

Why it happens

LangGraph executes graphs in supersteps, one node transition per step. To keep an infinite cycle from hanging forever, the runner raises GraphRecursionError after recursion_limit supersteps. The default is 25. Agent-style graphs with tool-calling loops routinely need 30-100 steps, so the default is too low for them, but exactly right for simple Q and A flows where hitting it always means a cycle.

Edge cases

• Streaming: pass the config to graph.stream() the same way; the limit applies per run.
• astream_events: same; the config key is recursion_limit there too.
• Very large limits (1000+): fine for batch agents, but a real cycle will now burn that many LLM calls before failing. Keep a wall-clock timeout alongside.
• recursion_limit below your legit step count in tests: tests with simple fixtures pass at 25 while production with retries needs 100. Set the limit from a constant per environment, not per call site, so the two stay in sync.
• Checkpointing: when the limit is hit the run raises, but checkpoints written by completed steps are still there. Resume from the checkpoint instead of rerunning from scratch.

Tool compatibility

• langgraph (Python) all recent releases; langgraph.errors.GraphRecursionError is the documented import path.
• Applies to StateGraph, compiled graphs, subgraphs, and create_react_agent-style agent graphs.