langchain-ai/deepagents · error · TypeError

recursion_limit must be None or a positive integer

Error message

recursion_limit must be None or a positive integer

What it means

ServerConfig.__post_init__ validates that recursion_limit is either None (unlimited/default) or a positive integer. A bool raises TypeError because bool is a subclass of int in Python and passing True/False is almost always a config bug, not an intentional limit. This prevents silently treating True as 1.

Source

Thrown at libs/code/deepagents_code/_server_config.py:512

                raise ValueError(msg)
            if "read_file" not in self.allow_fs_tools:
                msg = "allow_fs_tools must include 'read_file'"
                raise ValueError(msg)
        if isinstance(self.rubric_max_iterations, bool):
            msg = "rubric_max_iterations must be None or a positive integer"
            raise TypeError(msg)
        if self.rubric_max_iterations is not None and self.rubric_max_iterations <= 0:
            msg = "rubric_max_iterations must be None or a positive integer"
            raise ValueError(msg)
        if isinstance(self.cli_max_retries, bool):
            msg = "cli_max_retries must be None or a non-negative integer"
            raise TypeError(msg)
        if self.cli_max_retries is not None and self.cli_max_retries < 0:
            msg = "cli_max_retries must be None or a non-negative integer"
            raise ValueError(msg)
        if isinstance(self.recursion_limit, bool):
            msg = "recursion_limit must be None or a positive integer"
            raise TypeError(msg)
        if self.recursion_limit is not None and self.recursion_limit <= 0:
            msg = "recursion_limit must be None or a positive integer"
            raise ValueError(msg)

    # ------------------------------------------------------------------
    # Serialization
    # ------------------------------------------------------------------

    def to_env(self) -> dict[str, str | None]:
        """Serialize this config to a `DEEPAGENTS_CODE_SERVER_*` env-var mapping.

        `None` values signal that the variable should be *cleared* from the
        environment (rather than set to an empty string), so callers can
        iterate and set or clear each variable in `os.environ`.

        Returns:
            Dict mapping env-var suffixes (without the prefix) to their
                string values or `None`.

View on GitHub (pinned to a1af029e6e)

Solutions

  1. Set recursion_limit to a positive integer such as 25, or omit it / explicitly set it to null for the default.
  2. If the value comes from a config file or env var, coerce it with int(value) and skip the key when unset or empty.
  3. Search your config loading code for bool coercion (e.g. strtobool) that may convert 'true' into a bool before reaching ServerConfig.

Example fix

# before
ServerConfig(recursion_limit=True)
# after
ServerConfig(recursion_limit=25)  # or None
Defensive patterns

Strategy: validation

Validate before calling

def valid_recursion_limit(v):
    return v is None or (isinstance(v, int) and not isinstance(v, bool) and v > 0)
if not valid_recursion_limit(cfg.get("recursion_limit")):
    raise ValueError("recursion_limit must be None or a positive integer")

Type guard

def is_recursion_limit(v) -> bool:
    return v is None or (isinstance(v, int) and not isinstance(v, bool) and v > 0)

Prevention

When it happens

Trigger: Constructing ServerConfig (directly or via from_cli_args/deserialization) with recursion_limit=True or False, or recursion_limit=0 or a negative integer, triggers __post_init__ at line 512 (TypeError) or 514 (ValueError).

Common situations: YAML/JSON config files where a boolean flag was placed in the recursion_limit key; CLI/env parsing code that passes a truthy/falsy value instead of an int; template configs left as recursion_limit: true.

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

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