BerriAI/litellm · error · TimeoutError

OpenSandbox execd endpoint for {sandbox_id} was not ready wi

Error message

OpenSandbox execd endpoint for {sandbox_id} was not ready within {ready_timeout} seconds

What it means

After a sandbox reaches Running, LiteLLM polls the execd endpoint via GET /sandboxes/{id}/endpoints/{OPEN_SANDBOX_EXECD_PORT}, treating 404 (and transient ValueErrors) as 'not registered yet'. If the ready_timeout deadline passes first, TimeoutError is raised chained (from) the last observed error, so the cause is available via __cause__.

Source

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

        last_error: Exception | None = None
        while True:
            try:
                return await self._get_execd_endpoint(
                    sandbox_id=sandbox_id,
                    api_base=api_base,
                    headers=headers,
                    use_server_proxy=use_server_proxy,
                    client=client,
                )
            except httpx.HTTPStatusError as e:
                if e.response.status_code != 404:
                    raise
                last_error = e
            except ValueError as e:
                last_error = e

            if time.monotonic() >= deadline:
                raise TimeoutError(
                    f"OpenSandbox execd endpoint for {sandbox_id} was not ready within {ready_timeout} seconds"
                ) from last_error
            await asyncio.sleep(poll_interval)

    async def _get_execd_endpoint(
        self,
        *,
        sandbox_id: str,
        api_base: str,
        headers: dict[str, str],
        use_server_proxy: bool,
        client: AsyncHTTPHandler | None,
    ) -> tuple[str, dict[str, str]]:
        response: Final = cast(
            httpx.Response,
            await self._http(client).get(
                url=f"{api_base}/sandboxes/{sandbox_id}/endpoints/{OPEN_SANDBOX_EXECD_PORT}",
                headers=headers,

View on GitHub (pinned to 77b7c6c40c)

Solutions

Raise ready_timeout for the execd wait
Verify the sandbox image actually runs execd on OPEN_SANDBOX_EXECD_PORT
Inspect e.__cause__ (last 404 or ValueError) to distinguish 'not yet registered' from other failures
Recreate the sandbox if endpoint registration is genuinely stuck

Defensive patterns

Strategy: retry

Try / catch

Catch TimeoutError and inspect e.__cause__ (the last 404 or ValueError): if it is a 404 pattern, retry with a larger ready_timeout since registration lag is transient; if the cause differs, recreate the sandbox.

Prevention

Verify the sandbox image actually starts execd on OPEN_SANDBOX_EXECD_PORT before relying on it
Budget a longer timeout for endpoint registration than for sandbox boot
Distinguish boot timeouts from endpoint-registration timeouts in metrics

When it happens

Trigger: The execd sidecar inside a Running sandbox is slow to register its endpoint, the sandbox image never starts execd on the expected port, or endpoint records replicate slowly in the control plane - every poll 404s until the deadline expires.

Common situations: Custom sandbox images that lack the execd service; heavy startup work inside the sandbox delaying execd; control-plane lag during incidents; ready_timeout too small for endpoint registration.

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/fbb2f182f27192be. Report an issue: GitHub.