BerriAI/litellm · error · ValueError

LEVOAI_ORG_ID environment variable is required for Levo…

Error message

LEVOAI_ORG_ID environment variable is required for Levo integration.

What it means

The Levo integration (an OpenTelemetry-based observability callback) validates its required environment variables in the logger constructor and raises ValueError when one is missing. LEVOAI_ORG_ID specifically identifies your organization and is sent as the x-levo-organization-id header on every OTLP export, so telemetry cannot be routed without it. The check runs after the LEVOAI_API_KEY check and before LEVOAI_WORKSPACE_ID / LEVOAI_COLLECTOR_URL, so seeing this error means the API key is already set.

Solutions

Set LEVOAI_ORG_ID in the environment of the process running litellm: export LEVOAI_ORG_ID=<value from Levo dashboard>
Verify all four required vars are non-empty before startup: for v in LEVOAI_API_KEY LEVOAI_ORG_ID LEVOAI_WORKSPACE_ID LEVOAI_COLLECTOR_URL; do [ -n "$v" ] || echo missing $v; done (check via printenv if needed)
If running under Docker/systemd/supervisor, confirm the variable is passed into that execution context (docker-compose environment: block, systemd Environment=, etc.), not just your shell
Redeploy/restart so the callback constructor re-runs validation

Example fix

# before (only the API key is set)
LEVOAI_API_KEY=lv-****
# after (all four required vars)
LEVOAI_API_KEY=lv-****
LEVOAI_ORG_ID=your-org-id
LEVOAI_WORKSPACE_ID=your-workspace-id
LEVOAI_COLLECTOR_URL=https://collector.levo.ai

Defensive patterns

Strategy: validation

Validate before calling

import os

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

Try / catch

try:
    from litellm.integrations.levo.levo import LevoLogger  # construct callback
    cb = LevoLogger()
except ValueError as e:
    # env validation failure: report and fail deployment, do not retry
    raise RuntimeError(f'Levo callback misconfigured: {e}') from e

Prevention

Declare all four LEVOAI_* variables in the same env file/template so they are reviewed together
Add a startup preflight that asserts every required integration env var before litellm boots
Fail CI deployments on missing env rather than discovering the ValueError at runtime
Keep a runbook entry mapping each Levo var to where its value comes from (dashboard vs support email)

When it happens

Trigger: Instantiating the Levo callback (via litellm.callbacks, litellm_settings.callbacks in config.yaml, or direct construction) in a process where LEVOAI_API_KEY is present but LEVOAI_ORG_ID is unset or an empty string. Typical in CI, Docker, or a .env that only copied some of the four LEVOAI_* values from the Levo dashboard.

Common situations: Partial .env files (API key copied but org/workspace/collector URL forgotten), docker-compose services that define only some LEVOAI_* variables, secrets managers that sync a subset of keys, or trailing-whitespace/empty-string values that still fail the truthiness check.

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

Appendix: source

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

        Retrieves the Levo configuration based on environment variables.

        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}")

View on GitHub (pinned to 77b7c6c40c)