BerriAI/litellm · error · TimeoutError

OpenSandbox sandbox {sandbox_id} was not Running within {rea

Error message

OpenSandbox sandbox {sandbox_id} was not Running within {ready_timeout} seconds

What it means

The OpenSandbox boot wait loop polls the sandbox state until it equals Running. When the monotonic deadline (ready_timeout seconds, checked with time.monotonic()) passes while the sandbox is still in a non-terminal state like Pending or Creating, TimeoutError is raised with the configured timeout value.

Source

Thrown at litellm/llms/opensandbox/sandbox/transformation.py:262

        poll_interval: float,
    ) -> None:
        deadline: Final = time.monotonic() + ready_timeout
        while True:
            response = cast(
                httpx.Response,
                await self._http(client).get(
                    url=f"{api_base}/sandboxes/{sandbox_id}",
                    headers=headers,
                ),
            )
            data = response.json()
            state = self._sandbox_state(data)
            if state == "Running":
                return
            if state in {"Failed", "Stopping", "Terminated"}:
                raise ValueError(f"OpenSandbox sandbox {sandbox_id} entered {state}")
            if time.monotonic() >= deadline:
                raise TimeoutError(f"OpenSandbox sandbox {sandbox_id} was not Running within {ready_timeout} seconds")
            await asyncio.sleep(poll_interval)

    async def _wait_for_execd_endpoint(
        self,
        *,
        sandbox_id: str,
        api_base: str,
        headers: dict[str, str],
        use_server_proxy: bool,
        client: AsyncHTTPHandler | None,
        ready_timeout: float,
        poll_interval: float,
    ) -> tuple[str, dict[str, str]]:
        deadline: Final = time.monotonic() + ready_timeout
        last_error: Exception | None = None
        while True:
            try:
                return await self._get_execd_endpoint(

View on GitHub (pinned to 77b7c6c40c)

Solutions

Increase ready_timeout in the OpenSandbox call/config
Retry sandbox creation - sandboxes stuck in Pending often succeed on a second attempt
Use a smaller or pre-warmed image to cut boot time
Check the provider status page for provisioning delays

Defensive patterns

Strategy: retry

Try / catch

Catch TimeoutError separately from ValueError: log elapsed provisioning time, then retry create-with-wait once or twice with a larger ready_timeout before surfacing the failure - Pending/Creating states are usually transient, unlike terminal states.

Prevention

Set ready_timeout generously for first-boot or large images
Alert on repeated provisioning timeouts to detect capacity problems early
Prefer pre-warmed images in latency-sensitive paths

When it happens

Trigger: Sandbox provisioning takes longer than ready_timeout: cold-start image pulls, provider capacity pressure, very large images or resource requests, or ready_timeout left at a small default.

Common situations: Peak-hour provisioning delays; first-boot of a heavy custom image; network latency between litellm and the sandbox control plane; timeouts set for fast images then reused for slow ones.

Understand the failure class

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

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/fd04288c83683e3c. Report an issue: GitHub.