BerriAI/litellm · error · ValueError

OpenSandbox api_base is required. Pass api_base or set {OPEN

Error message

OpenSandbox api_base is required. Pass api_base or set {OPEN_SANDBOX_API_BASE_ENV_VAR}.

What it means

Every OpenSandbox lifecycle call (create, wait, exec) needs the control-plane base URL. The static helper _api_base() falls back from the explicit api_base argument to the OPEN_SANDBOX_API_BASE environment variable; when both are absent it raises this ValueError before any network I/O happens.

Source

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

        if not isinstance(data, dict):
            return None
        status: Final = data.get("status")
        if not isinstance(status, dict):
            return None
        state: Final = status.get("state")
        return str(state) if state is not None else None

    @staticmethod
    def _as_str_dict(value: object) -> dict[str, str]:
        if not isinstance(value, dict):
            return {}
        return {str(k): str(v) for k, v in value.items()}

    @staticmethod
    def _api_base(api_base: str | None) -> str:
        base: Final = api_base or get_secret_str(OPEN_SANDBOX_API_BASE_ENV_VAR)
        if not base:
            raise ValueError(f"OpenSandbox api_base is required. Pass api_base or set {OPEN_SANDBOX_API_BASE_ENV_VAR}.")
        return str(base).rstrip("/")

    @staticmethod
    def _lifecycle_headers(api_key: str) -> dict[str, str]:
        headers: Final = {"Content-Type": "application/json"}
        if api_key:
            headers["OPEN-SANDBOX-API-KEY"] = api_key
        return headers

    @staticmethod
    def _endpoint_base_url(endpoint: str, api_base: str) -> str:
        normalized_endpoint: Final = endpoint.rstrip("/")
        if normalized_endpoint.startswith(("http://", "https://")):
            return normalized_endpoint
        protocol: Final = api_base.split("://", 1)[0] if "://" in api_base else "http"
        return f"{protocol}://{normalized_endpoint}"

    @staticmethod

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. export OPEN_SANDBOX_API_BASE=https://<your-opensandbox-host> in the process environment
2. Pass api_base explicitly on the call or in the litellm deployment config
3. Add a startup assertion that the variable resolves to catch this before traffic

Example fix

// before
result = litellm.opensandbox_create(...)  # no api_base anywhere

// after
import os
result = litellm.opensandbox_create(..., api_base=os.environ["OPEN_SANDBOX_API_BASE"])

import os

def opensandbox_configured() -> bool:
    return bool(os.getenv("OPEN_SANDBOX_API_BASE"))

assert opensandbox_configured(), "Set OPEN_SANDBOX_API_BASE or pass api_base"  # run at startup

try/except ValueError at the OpenSandbox call boundary can translate this deterministic config failure into a startup-time configuration error message for operators.

When it happens

Trigger: Invoking litellm's OpenSandbox provider (sandbox creation or code execution) without passing api_base and without OPEN_SANDBOX_API_BASE exported in the running process.

Common situations: Env var set in a dev shell but not in the container/serverless environment; variable name typo; assuming litellm ships a default OpenSandbox endpoint (it does not for lifecycle calls).

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• custom_ui_sso_sign_in_handler is not configured. Please set
• 🚨🚨🚨 DISABLING LLM API ENDPOINTS is an Enterprise feature
• 🚨🚨🚨 DISABLING ADMIN ENDPOINTS is an Enterprise feature 🚨
• Invalid mode: {custom_auth_settings['mode']}
• LLM Router not initialized. Ensure models added to proxy.

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