langchain-ai/deepagents · error · ValueError

recursion_limit must be positive

Error message

recursion_limit must be positive

What it means

DeepAgentRuntime.__init__ resolves the recursion limit from the explicit argument or the environment (via _recursion_limit_from_env) and raises this ValueError when the resolved value is zero or negative. LangGraph recursion limits must be positive integers, so a non-positive value would make every invocation fail.

Source

Thrown at libs/talon/deepagents_talon/runtime.py:254

        cron_store: CronJobStore | None = None,
        backend: BackendProtocol | None = None,
        skills: Sequence[str] | None = None,
        middleware: Sequence[AgentMiddleware[Any, Any, Any]] = (),
        interrupt_on: Mapping[str, bool | InterruptOnConfig] | None = None,
        memory: Sequence[str] | None = None,
        checkpointer: Checkpointer | None = None,
        include_web_tools: bool = True,
        recursion_limit: int = DEFAULT_RECURSION_LIMIT,
        max_retries: int = DEFAULT_MAX_RETRIES,
        max_continuations: int = DEFAULT_MAX_CONTINUATIONS,
        env: Mapping[str, str] | None = None,
    ) -> None:
        """Initialize without constructing the graph."""
        values = os.environ if env is None else env
        resolved_recursion_limit = _recursion_limit_from_env(values, recursion_limit)
        if resolved_recursion_limit <= 0:
            msg = "recursion_limit must be positive"
            raise ValueError(msg)
        if max_retries < 1:
            msg = "max_retries must be at least 1"
            raise ValueError(msg)
        if max_continuations < 0:
            msg = "max_continuations cannot be negative"
            raise ValueError(msg)

        self.model = model
        self.tools = tuple(tools)
        self.system_prompt = system_prompt
        self.subagents = tuple(subagents) if subagents is not None else None
        self._has_async_subagents = _has_async_subagents(self.subagents)
        self.assistant_dir = assistant_dir
        self.cron_store = cron_store
        self.env = dict(os.environ if env is None else env)
        self.backend = backend if backend is not None else _default_backend(self.env)
        self.skills = tuple(skills) if skills is not None else None
        self.middleware = tuple(middleware)

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pass a positive recursion_limit (e.g. 25) to DeepAgentRuntime
2. Fix the environment variable that _recursion_limit_from_env reads to a positive integer (e.g. `export AGENT_RECURSION_LIMIT=50`)
3. Remove the env variable entirely so the built-in default is used

Example fix

// before
os.environ["AGENT_RECURSION_LIMIT"] = "0"
runtime = DeepAgentRuntime(...)
// after
os.environ["AGENT_RECURSION_LIMIT"] = "50"
runtime = DeepAgentRuntime(...)  # or pass recursion_limit=50 explicitly

import os

def resolve_limit(env: dict[str, str] | None = None) -> int:
    raw = (env or os.environ).get("AGENT_RECURSION_LIMIT")
    value = int(raw) if raw and raw.strip() else 25
    if value <= 0:
        raise ValueError("AGENT_RECURSION_LIMIT must be a positive integer")
    return value

runtime = DeepAgentRuntime(..., recursion_limit=resolve_limit())

def is_positive_int(v: object) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and v > 0

When it happens

Trigger: Constructing DeepAgentRuntime with recursion_limit <= 0, or with recursion_limit=None while the corresponding env variable is set to 0, a negative number, or a value like '0'/'-5'.

Common situations: A deployment env file contains `AGENT_RECURSION_LIMIT=0` under the assumption it means 'unlimited'; a computed default produced 0; a template variable was left unsubstituted and stripped to an empty/invalid number.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• {key} must be a positive integer
• {what} must be absolute: {path}
• Home directory is not absolute: {launch_home}. Set $HOME to
• Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: unknown fil
• Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: {raw!r}; ex

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/b5580c82c761d678. Report an issue: GitHub.