BerriAI/litellm · error · ValueError

LEVOAI_COLLECTOR_URL environment variable is required for…

Error message

LEVOAI_COLLECTOR_URL environment variable is required for Levo integration. Please contact Levo support to get your collector URL.

What it means

The Levo integration constructor requires LEVOAI_COLLECTOR_URL and raises ValueError when it is unset or empty. Unlike the other Levo vars, the collector URL is the OTLP HTTP endpoint your telemetry is POSTed to, and it is used exactly as provided (no normalization), which is why the message directs you to Levo support to obtain it. Hitting this error means API key, org ID, and workspace ID have already passed validation.

Solutions

Contact Levo support (or check your Levo onboarding material) for your dedicated collector URL, then export LEVOAI_COLLECTOR_URL=<https://your-collector-host>
Pass the variable through to the runtime context (docker-compose environment block, Kubernetes secret/env, systemd Environment=) and confirm with printenv inside that context
Provide the URL exactly as given — the code uses it verbatim as the OTLP HTTP endpoint, so do not append paths or trailing slashes unless Levo specifies them
Restart litellm so constructor validation passes

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

import os

collector = os.environ.get('LEVOAI_COLLECTOR_URL')
if not collector or not collector.startswith(('http://', 'https://')):
    raise SystemExit('LEVOAI_COLLECTOR_URL must be set to a valid http(s) collector URL (obtain it from Levo support)')

Try / catch

try:
    cb = LevoLogger()
except ValueError as e:
    raise RuntimeError(f'Levo callback misconfigured: {e}') from e

Prevention

Record the collector URL in your secret manager at onboarding time — it cannot be derived from other Levo values
Validate the URL scheme at deploy time; the integration uses it verbatim with no normalization
Parametrize per-environment collector URLs (staging vs prod) in your deployment templates
Add a synthetic telemetry send in a smoke test to confirm the collector URL is reachable

When it happens

Trigger: Enabling the Levo callback when LEVOAI_COLLECTOR_URL is not set in the process environment. This is the most commonly missed var because it is tenant-specific (a dedicated collector hostname) rather than something copyable from a shared account page, and onboarding often delivers it in a support email that gets lost.

Common situations: New Levo customers who have API key/org/workspace but were never sent the collector hostname; per-tenant collector URLs not templated into Helm values or docker-compose; the var defined in a base env file but overridden to empty in an overlay; deploying to a new environment (staging to prod) without porting the URL.

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

Appendix: source

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

        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)

        return LevoConfig(
            otlp_auth_headers=otlp_auth_headers,

View on GitHub (pinned to 77b7c6c40c)