What causes "timeout must be non-negative, got {timeout}" in langchain-ai/deepagents?

Fix the caller/config so `timeout >= 0`; clamp with `max(0, value)`.

langchain-ai/deepagents · error · ValueError

timeout must be non-negative, got {timeout}

Error message

timeout must be non-negative, got {timeout}

What it means

`VercelSandbox.__init__` validates the `timeout` parameter and raises `ValueError` if it is negative. The timeout is the default maximum duration in seconds for sandbox operations, so a negative value is always a programming/config error and is rejected eagerly rather than surfacing later inside an operation.

Source

Thrown at libs/partners/vercel/langchain_vercel_sandbox/sandbox.py:53

        self,
        *,
        sandbox: Sandbox,
        timeout: int = 30 * 60,
    ) -> None:
        """Create a backend wrapping an existing Vercel sandbox.

        Args:
            sandbox: Existing Vercel sandbox instance to wrap.
            timeout: Default command timeout in seconds used when `execute()` is
                called without an explicit `timeout`. A timeout of 0 waits
                indefinitely; negative values are rejected.

        Raises:
            ValueError: If `timeout` is negative.
        """
        if timeout < 0:
            msg = f"timeout must be non-negative, got {timeout}"
            raise ValueError(msg)
        self._sandbox = sandbox
        self._default_timeout = timeout

    @property
    def id(self) -> str:
        """Return the Vercel sandbox id."""
        return self._sandbox.sandbox_id

    def execute(
        self,
        command: str,
        *,
        timeout: int | None = None,
    ) -> ExecuteResponse:
        """Execute a shell command inside the sandbox.

        Args:
            command: Shell command string to execute.

View on GitHub (pinned to a1af029e6e)

Solutions

Fix the caller/config so `timeout >= 0`; clamp with `max(0, value)`.
Validate the configured timeout at config-load time before constructing the sandbox.
Use `timeout=0` (or omit it for the default) if you truly want no/immediate timeout semantics.
Audit computed values like `deadline - now` and guard against elapsed deadlines.

Example fix

// before
timeout = int(os.environ["VERCEL_TIMEOUT"])  # may be -1
sb = VercelSandbox(sandbox=vs, timeout=timeout)  # ValueError

// after
timeout = max(0, int(os.environ.get("VERCEL_TIMEOUT", 300)))
sb = VercelSandbox(sandbox=vs, timeout=timeout)

Defensive patterns

Strategy: validation

Validate before calling

def normalize_timeout(value: int | float | str | None, default: int = 300) -> int:
    if value is None:
        return default
    return max(0, int(value))

Type guard

def is_valid_timeout(timeout: int) -> bool:
    return isinstance(timeout, int) and timeout >= 0

Try / catch

try:
    sb = VercelSandbox(sandbox=vs, timeout=timeout)
except ValueError as e:
    log.error("bad timeout config: %s", e)
    sb = VercelSandbox(sandbox=vs, timeout=300)

Prevention

Validate/clamp timeout values at config-load time, not at sandbox construction.
Use non-negative types or sentinel defaults for deadline-derived durations; guard `deadline - now` against elapsed deadlines.
Add a schema/unit check for timeout fields in config files (>= 0).
Prefer omitting `timeout` to accept the library default unless you need a custom cap.

When it happens

Trigger: Constructing `VercelSandbox(sandbox=..., timeout=n)` with a negative `n` — typically from an unvalidated config file, env var, or computed duration (e.g. `deadline - now` after the deadline has passed).

Common situations: Config parsing that doesn't clamp values (`timeout: -1` in YAML/TOML); subtracting timestamps where the deadline already elapsed; sign errors when converting minutes to seconds.

Understand the failure class

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

Related errors

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