BerriAI/litellm · error · ValueError

LEVOAI_WORKSPACE_ID environment variable is required for…

Error message

LEVOAI_WORKSPACE_ID environment variable is required for Levo integration.

What it means

The Levo integration constructor validates required environment variables and raises ValueError when LEVOAI_WORKSPACE_ID is unset or empty. The workspace ID is sent as the x-levo-workspace-id header on every OTLP export so Levo can attribute telemetry to a workspace within your organization. Reaching this error means LEVOAI_API_KEY and LEVOAI_ORG_ID already passed their checks.

Solutions

Set LEVOAI_WORKSPACE_ID in the process environment: export LEVOAI_WORKSPACE_ID=<workspace id from Levo>
Audit all four LEVOAI_* variables for presence and non-emptiness before starting litellm (e.g. a startup check that fails fast with the list of missing keys)
Verify the variable reaches the actual runtime context (container, systemd unit, CI runner), not just your interactive shell
Restart the process so the callback revalidates

Example fix

# before
LEVOAI_API_KEY=lv-****
LEVOAI_ORG_ID=org-123
# after
LEVOAI_API_KEY=lv-****
LEVOAI_ORG_ID=org-123
LEVOAI_WORKSPACE_ID=ws-456
LEVOAI_COLLECTOR_URL=https://collector.levo.ai

Defensive patterns

Strategy: validation

Validate before calling

import os

missing = [k for k in ('LEVOAI_API_KEY','LEVOAI_ORG_ID','LEVOAI_WORKSPACE_ID','LEVOAI_COLLECTOR_URL') if not os.environ.get(k)]
assert not missing, f'missing Levo env vars: {missing}'

Try / catch

try:
    cb = LevoLogger()
except ValueError as e:
    # name the missing var from the message and stop startup
    raise RuntimeError(f'Levo callback misconfigured: {e}') from e

Prevention

Treat the four LEVOAI_* vars as one unit in Helm values/docker-compose — add or remove them together
Automate pulling workspace/org IDs from the Levo dashboard rather than hand-copying
Log a sanitized list (names only) of missing required vars at process start
Integration-test the callback construction in CI with the same secret set as production

When it happens

Trigger: Registering the Levo callback (litellm.callbacks = [...], config.yaml litellm_settings.callbacks, or direct instantiation) where LEVOAI_WORKSPACE_ID is unset or empty while LEVOAI_API_KEY and LEVOAI_ORG_ID are set. Common when the Levo onboarding email listed the org ID but not the workspace ID, or the workspace was created after the .env was written.

Common situations: Copying only two or three of the four LEVOAI_* values from the Levo dashboard; creating a new Levo workspace and forgetting to update the deployment env; empty-string defaults in Kubernetes secrets or CI variable masks; env vars set in a different shell than the one launching the proxy.

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

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

Appendix: source

Thrown at litellm/integrations/levo/levo.py:63

        Returns:
            LevoConfig: Configuration object containing Levo OTLP settings.

        Raises:
            ValueError: If required environment variables are missing.
        """
        # Required environment variables
        api_key: Final = os.environ.get("LEVOAI_API_KEY", None)
        org_id: Final = os.environ.get("LEVOAI_ORG_ID", None)
        workspace_id: Final = os.environ.get("LEVOAI_WORKSPACE_ID", None)
        collector_url: Final = os.environ.get("LEVOAI_COLLECTOR_URL", None)

        # Validate required env vars
        if not api_key:
            raise ValueError("LEVOAI_API_KEY environment variable is required for Levo integration.")
        if not org_id:
            raise ValueError("LEVOAI_ORG_ID environment variable is required for Levo integration.")
        if not workspace_id:
            raise ValueError("LEVOAI_WORKSPACE_ID environment variable is required for Levo integration.")
        if not collector_url:
            raise ValueError(
                "LEVOAI_COLLECTOR_URL environment variable is required for Levo integration. "
                "Please contact Levo support to get your collector URL."
            )

        # Use collector URL exactly as provided by the user
        endpoint: Final = collector_url
        protocol: Final[Protocol] = "otlp_http"

        # Build OTLP headers string
        # Format: Authorization=Bearer {api_key},x-levo-organization-id={org_id},x-levo-workspace-id={workspace_id}
        headers_parts: Final = [f"Authorization=Bearer {api_key}"]
        headers_parts.append(f"x-levo-organization-id={org_id}")
        headers_parts.append(f"x-levo-workspace-id={workspace_id}")

        otlp_auth_headers: Final = ",".join(headers_parts)

View on GitHub (pinned to 77b7c6c40c)