What causes "OpenSandbox sandbox {sandbox_id} entered {state}" in BerriAI/litellm?

Query GET {api_base}/sandboxes/{id} with the same lifecycle headers to read the full sandbox record and failure reason

BerriAI/litellm · error · ValueError

OpenSandbox sandbox {sandbox_id} entered {state}

Error message

OpenSandbox sandbox {sandbox_id} entered {state}

What it means

While waiting for an OpenSandbox sandbox to boot, LiteLLM polls GET {api_base}/sandboxes/{id} and inspects the state field. If the state becomes Failed, Stopping, or Terminated, it raises ValueError immediately: the sandbox can never reach Running, so waiting longer or retrying the wait is pointless. A new sandbox must be created.

Source

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

        client: AsyncHTTPHandler | None,
        ready_timeout: float,
        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:

View on GitHub (pinned to 77b7c6c40c)

Solutions

Query GET {api_base}/sandboxes/{id} with the same lifecycle headers to read the full sandbox record and failure reason
Verify the image name and resource options passed to the create call
Delete the dead sandbox and recreate with corrected parameters - terminal states are unrecoverable
Confirm the lifecycle API key and api_base are valid for the account

Defensive patterns

Strategy: fallback

Try / catch

Wrap create-and-wait in try/except ValueError; when the message contains 'entered Failed', 'Stopping', or 'Terminated', delete the dead sandbox, recreate with corrected parameters (image/resources/key), and if creation keeps failing, fall back to a different sandbox provider - never re-wait on a terminal sandbox.

Prevention

Validate image names and resource options against provider docs before create
Treat terminal states as unrecoverable: recreate, do not extend the wait
Log sandbox IDs and states so recurring creation failures are traceable to a cause

When it happens

Trigger: Creating an OpenSandbox sandbox via litellm (code execution tooling) with an invalid image, unsupported resources, expired/invalid lifecycle API key, or a provider-side crash - the poll loop then observes a terminal state instead of Running.

Common situations: Typo'd or unavailable sandbox image name; quota/permission issues on the OpenSandbox account surfacing as async creation failure; provider incidents marking sandboxes Failed during provisioning.

Related errors

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