BerriAI/litellm · error · ValueError

PHOENIX_API_KEY must be set when using Phoenix Cloud…

Error message

PHOENIX_API_KEY must be set when using Phoenix Cloud (app.phoenix.arize.com).

What it means

When the Arize Phoenix tracer sends OTLP spans to a Phoenix Cloud endpoint (host contains 'app.phoenix.arize.com'), authentication is mandatory. In `get_arize_phoenix_config`, if no api_key was supplied and the resolved endpoint is Phoenix Cloud, litellm raises this ValueError instead of silently sending unauthenticated spans that would be rejected.

Solutions

1. Set PHOENIX_API_KEY in the process environment before enabling the callback: `export PHOENIX_API_KEY=your_phoenix_api_key`
2. Or pass the key explicitly when configuring the callback (api_key argument / `PHOENIX_API_KEY` in the proxy env)
3. If you did not intend to use Phoenix Cloud, point PHOENIX_COLLECTOR_ENDPOINT back at your local/collector endpoint so the Cloud check does not fire

Example fix

# before
os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "https://app.phoenix.arize.com/v1/traces"
litellm.callbacks = ["arize_phoenix"]  # ValueError: PHOENIX_API_KEY must be set

# after
os.environ["PHOENIX_API_KEY"] = "phoenix-key-123"
os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "https://app.phoenix.arize.com/v1/traces"
litellm.callbacks = ["arize_phoenix"]

import os

endpoint = os.getenv("PHOENIX_COLLECTOR_ENDPOINT", "")
if "app.phoenix.arize.com" in endpoint and not os.getenv("PHOENIX_API_KEY"):
    raise SystemExit("Phoenix Cloud endpoint requires PHOENIX_API_KEY")
litellm.callbacks = ["arize_phoenix"]

def phoenix_cloud_needs_key(endpoint: str, api_key: str | None) -> bool:
    return "app.phoenix.arize.com" in endpoint and not api_key

try:
    litellm.callbacks = ["arize_phoenix"]
except ValueError as e:
    if "PHOENIX_API_KEY" in str(e):
        # skip tracing for Cloud until key is provisioned; keep serving
        litellm.callbacks = [c for c in (litellm.callbacks or []) if c != "arize_phoenix"]
        log.warning("Phoenix tracing disabled: %s", e)
    else:
        raise

When it happens

Trigger: Enabling the Arize Phoenix callback (`litellm.callbacks = ["arize_phoenix"]`) with PHOENIX_COLLECTOR_ENDPOINT pointing at app.phoenix.arize.com (or its OTLP/gRPC variants) but no api_key argument and no PHOENIX_API_KEY env var.

Common situations: Migrating from a local Phoenix (http://localhost:6006/v1/traces, where auth is skipped) to Phoenix Cloud without adding the key; setting the collector endpoint via PHOENIX_COLLECTOR_ENDPOINT in one place and the key in another that never reaches the process; proxy deployments where the env var is missing from the container.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

• api_key is required
• API key is required
• api_key is required for Volcengine authentication
• Authentication failed. Check your Arize Phoenix API key and…
• Failed to fetch AgentOps token

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

Appendix: source

Thrown at litellm/integrations/arize/arize_phoenix.py:436

                        endpoint = f"{collector_endpoint}v1/traces"
                    else:
                        endpoint = f"{collector_endpoint}/v1/traces"
                else:
                    endpoint = collector_endpoint
                protocol = "otlp_http"
        else:
            endpoint = "http://localhost:6006/v1/traces"
            protocol = "otlp_http"
            verbose_logger.debug(
                "No PHOENIX_COLLECTOR_ENDPOINT found, using default local Phoenix endpoint: %s", endpoint
            )

        otlp_auth_headers = None
        if api_key is not None:
            auth_header_key = "authorization" if protocol == "otlp_grpc" else "Authorization"
            otlp_auth_headers = f"{auth_header_key}=Bearer {api_key}"
        elif "app.phoenix.arize.com" in endpoint:
            raise ValueError("PHOENIX_API_KEY must be set when using Phoenix Cloud (app.phoenix.arize.com).")

        project_name: Final = os.environ.get("PHOENIX_PROJECT_NAME") or "default"

        return ArizePhoenixConfig(
            otlp_auth_headers=otlp_auth_headers,
            protocol=protocol,
            endpoint=endpoint,
            project_name=project_name,
        )

    async def async_health_check(self):
        config: Final = self.get_arize_phoenix_config()

        if not config.otlp_auth_headers:
            return {
                "status": "unhealthy",
                "error_message": "PHOENIX_API_KEY environment variable not set",
            }

View on GitHub (pinned to 77b7c6c40c)