langchain-ai/deepagents · error · TypeError

rubric_max_iterations must be None or a positive integer

Error message

rubric_max_iterations must be None or a positive integer

What it means

ServerConfig validates rubric_max_iterations: booleans are rejected with a TypeError (bool is a subclass of int in Python and would silently pass numeric checks) and non-positive integers are rejected with this ValueError. The field must be None (unlimited/default behavior) or an integer >= 1. This error fires when a non-None, <= 0 integer is supplied.

Source

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

            msg = "shell_allow_list must be None or non-empty"
            raise ValueError(msg)
        # `allow_fs_tools` is a security control: `None` means unrestricted, but
        # an explicit list must be a usable allowlist. Own the non-empty +
        # `read_file`-required invariant here (the single authoritative point
        # for both the env round-trip via `from_env` and direct construction)
        # rather than deferring to `FilesystemMiddleware`, which would only
        # surface the violation a process boundary away. `_parse_allow_fs_tools_flag`
        # still enforces the same rule at the CLI for a friendlier error.
        if self.allow_fs_tools is not None:
            if len(self.allow_fs_tools) == 0:
                msg = "allow_fs_tools must be None or a non-empty list"
                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

View on GitHub (pinned to a1af029e6e)

Solutions

1. Set rubric_max_iterations to a positive integer (>= 1), e.g. 5
2. Set rubric_max_iterations=None to use the library default instead of 0
3. Fix the upstream source (env var parse, computed value) so 'disabled' is represented as None, not 0

Example fix

// before
config = ServerConfig(rubric_max_iterations=int(os.environ.get('RUBRIC_ITERS', 0)))
// after
raw = os.environ.get('RUBRIC_ITERS')
config = ServerConfig(rubric_max_iterations=int(raw) if raw else None)

def validate_rubric_max_iterations(v):
    if isinstance(v, bool):
        raise TypeError("rubric_max_iterations must be None or a positive integer")
    if v is not None and v <= 0:
        raise ValueError("rubric_max_iterations must be None or a positive integer")

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

try:
    config = ServerConfig(rubric_max_iterations=value)
except (TypeError, ValueError) as e:
    if "rubric_max_iterations" in str(e):
        config = ServerConfig(rubric_max_iterations=None)  # fall back to default
    else:
        raise

When it happens

Trigger: Constructing ServerConfig with rubric_max_iterations=0 or any negative integer (e.g. -1). Note rubric_max_iterations=True raises a TypeError instead, and the same message is also raised at line 503 (error 47) from the companion <= 0 check.

Common situations: Reading the limit from env/config and parsing an unset value as 0; a loop-computation that produced -1 as a sentinel; copying a 0-based config convention from another setting that uses 0 to mean 'off'.

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

• cli_max_retries must be None or a non-negative integer
• allow_fs_tools must include 'read_file'
• Could not parse embedded resource block. Block expected eith
• question text must not be blank
• choice has a blank 'value': {choice!r}

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