langchain-ai/deepagents · error · ValueError

max_execute_timeout must be positive, got {max_execute_timeo

Error message

max_execute_timeout must be positive, got {max_execute_timeout}

What it means

FilesystemMiddleware validates that max_execute_timeout is a positive number; a zero or negative value is rejected in __init__ with this ValueError, since command execution must always have a meaningful timeout.

Source

Thrown at libs/deepagents/deepagents/middleware/filesystem.py:1700

                `"write_file"`, `"edit_file"`, `"delete"`, `"glob"`,
                `"grep"`, `"execute"` to restrict the model to only those
                tools; all others are hidden. `read_file` must be included
                in any list. Backend capability checks for `execute` and
                `delete` still apply; listing them when the backend does not
                support them is a no-op.
            _permissions: Optional filesystem permission rules enforced directly
                by this middleware's tool implementations.

                Marked private for now because this is an internal
                implementation detail and may move to the backend layer in a
                future change.
        """
        if isinstance(tools, list) and "read_file" not in tools:
            msg = "read_file must be included in tools; it is required by FilesystemMiddleware"
            raise ValueError(msg)
        if max_execute_timeout <= 0:
            msg = f"max_execute_timeout must be positive, got {max_execute_timeout}"
            raise ValueError(msg)
        if grep_max_count is not None and grep_max_count <= 0:
            msg = f"grep_max_count must be positive or None, got {grep_max_count}"
            raise ValueError(msg)
        # Use provided backend or default to StateBackend instance
        self.backend = backend if backend is not None else StateBackend()
        if callable(self.backend) and not isinstance(self.backend, BackendProtocol):
            msg = (
                "backend must be an initialized backend instance. Backend factories "
                "were removed in deepagents 0.7; pass StateBackend(), "
                "CompositeBackend(...), or another BackendProtocol instance instead."
            )
            raise TypeError(msg)
        self.state_schema = cast(
            "type[FilesystemState]",
            FilesystemState if _uses_state_backend(self.backend) else AgentState,
        )
        if _permissions and supports_execution(self.backend) and not _all_paths_scoped_to_routes(_permissions, self.backend):
            msg = (

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pass a positive timeout (e.g. max_execute_timeout=60)
2. Fix the env/config parsing that produced the non-positive value
3. Omit the parameter to use the default timeout

Example fix

// before
FilesystemMiddleware(max_execute_timeout=int(os.environ.get("EXEC_TIMEOUT", 0)))
// after
FilesystemMiddleware(max_execute_timeout=int(os.environ.get("EXEC_TIMEOUT", 300)))

timeout = int(os.environ.get("EXEC_TIMEOUT", 300))
if timeout <= 0:
    raise ValueError(f"EXEC_TIMEOUT must be positive, got {timeout}")

try:
    mw = FilesystemMiddleware(max_execute_timeout=timeout)
except ValueError as e:
    logger.error("invalid execute timeout: %s", e)
    timeout = 300
    mw = FilesystemMiddleware(max_execute_timeout=timeout)

When it happens

Trigger: FilesystemMiddleware(max_execute_timeout=0) or a negative value; computing the timeout from config/env where the value is missing (0) or mis-scaled (e.g. -1 as a sentinel).

Common situations: Env var like EXEC_TIMEOUT unset and int('') fallback to 0; config accidentally treating -1 as 'unlimited'; unit confusion (seconds vs ms yielding 0).

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Permission path must start with '/': {path!r}
• read_file must be included in tools; it is required by Files
• allow_list must not be empty; disable shell access instead
• interpreter_ptc='all' exposes every host tool to PTC calls t
• Invalid interpreter_ptc string {ptc!r}; expected 'safe', 'al

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