Heuristic:Langchain ai Langgraph Recursion Limit Tuning
| Knowledge Sources | |
|---|---|
| Domains | Reliability, Agents, Configuration |
| Last Updated | 2026-02-11 14:00 GMT |
Overview
Guidance on configuring the graph recursion limit to prevent infinite loops while allowing complex agent workflows to complete.
Description
LangGraph uses a recursion limit (internally called step limit) to cap the maximum number of supersteps a graph can execute. This prevents infinite loops from consuming unbounded memory and compute. The default value is 10,000 steps (configurable via the `LANGGRAPH_DEFAULT_RECURSION_LIMIT` environment variable). This is intentionally high to accommodate complex workflows, but most real-world graphs finish in far fewer steps. The limit is enforced by the Pregel runtime and raises `GraphRecursionError` when exceeded.
Usage
Use this heuristic when designing agentic workflows that may loop indefinitely (e.g., ReAct agents calling tools repeatedly) or when you need to constrain resource usage in production. It is also relevant when debugging `GraphRecursionError` exceptions.
The Insight (Rule of Thumb)
- Action: Set `recursion_limit` in the config dict when calling `graph.invoke()` or `graph.stream()`.
- Default Value: 10,000 steps (via `LANGGRAPH_DEFAULT_RECURSION_LIMIT` env var).
- Recommended Range: For most agents, 25-100 is sufficient. A ReAct agent typically uses 2-3 steps per tool call cycle (LLM call + tool execution + state update).
- Trade-off: Setting the limit too low causes legitimate workflows to fail with `GraphRecursionError`. Setting it too high allows runaway agents to consume excessive resources before being stopped.
- Environment Override: Set `LANGGRAPH_DEFAULT_RECURSION_LIMIT` to change the default globally without modifying code.
- Per-invocation Override: Pass `{"recursion_limit": N}` as the config argument to `invoke()` or `stream()`.
Reasoning
The default of 10,000 is chosen to be effectively unlimited for well-behaved workflows while still providing a safety net. In practice, a ReAct agent that makes 10 tool calls typically uses ~30 steps (3 per cycle). Setting a limit of 100 would accommodate ~30 tool calls, which covers most real-world scenarios. The `GraphRecursionError` includes a troubleshooting link to help users diagnose whether the limit needs adjustment or if there is a genuine infinite loop.
The error code system (`ErrorCode.GRAPH_RECURSION_LIMIT`) provides structured diagnostic information, directing users to the relevant documentation page for resolution.
Code Evidence
Default recursion limit from `libs/langgraph/langgraph/_internal/_config.py:31`:
DEFAULT_RECURSION_LIMIT = int(getenv("LANGGRAPH_DEFAULT_RECURSION_LIMIT", "10000"))
GraphRecursionError definition from `libs/langgraph/langgraph/errors.py:45-65`:
class GraphRecursionError(RecursionError):
"""Raised when the graph has exhausted the maximum number of steps.
This prevents infinite loops. To increase the maximum number of steps,
run your graph with a config specifying a higher `recursion_limit`.
Examples:
graph = builder.compile()
graph.invoke(
{"messages": [("user", "Hello, world!")]},
# The config is the second positional argument
{"recursion_limit": 1000},
)
"""
pass
Error code with documentation link from `libs/langgraph/langgraph/errors.py:37-42`:
def create_error_message(*, message: str, error_code: ErrorCode) -> str:
return (
f"{message}\n"
"For troubleshooting, visit: https://docs.langchain.com/oss/python/langgraph/"
f"errors/{error_code.value}"
)