What causes "api_key is required" in BerriAI/litellm?

Supply the Phoenix API key: set PHOENIX_API_KEY or pass api_key explicitly where the client is constructed

BerriAI/litellm · error · ValueError

api_key is required

Error message

api_key is required

What it means

ArizePhoenixClient is the HTTP client the prompt integration uses to fetch prompt versions from the Phoenix API. Its constructor requires a truthy api_key; it is used immediately to build the 'Authorization: Bearer <key>' header, so an empty/None key cannot be deferred. Missing key fails fast at construction.

Solutions

Supply the Phoenix API key: set PHOENIX_API_KEY or pass api_key explicitly where the client is constructed
For local Phoenix, generate/retrieve an API key from the Phoenix UI settings and use it — the client always sends Bearer auth
Check for empty-string env vars: `if not os.getenv('PHOENIX_API_KEY'): raise` early in your startup with a clearer message

Example fix

# before
client = ArizePhoenixClient(api_base="http://localhost:6006")  # api_key=None -> ValueError

# after
client = ArizePhoenixClient(
    api_key=os.environ["PHOENIX_API_KEY"],
    api_base="http://localhost:6006",
)

Defensive patterns

Strategy: validation

Validate before calling

import os

api_key = os.getenv("PHOENIX_API_KEY")
if not api_key:
    raise SystemExit("PHOENIX_API_KEY missing/empty — required even for local Phoenix")
client = ArizePhoenixClient(api_key=api_key, api_base="http://localhost:6006")

Type guard

def has_phoenix_key(api_key: str | None) -> bool:
    return bool(api_key and api_key.strip())

Try / catch

try:
    ArizePhoenixClient(api_key=api_key, api_base=api_base)
except ValueError as e:
    if "api_key is required" in str(e):
        raise SystemExit("Set PHOENIX_API_KEY (create one in Phoenix Settings → API Keys; required even locally)") from e
    raise

Prevention

Note the Phoenix client always requires a key, including local deployments — create a local key up front
Fail fast at startup on empty/whitespace env values, since empty strings are falsy and trigger this too

When it happens

Trigger: Instantiating ArizePhoenixClient(api_key=None) or api_key='' — typically indirectly when prompt_initializer found no api_key in litellm_params and PHOENIX_API_KEY was unset, or when the prompt manager is constructed directly in tests.

Common situations: Local Phoenix deployments where the developer assumed auth-free access (the client requires a key even for localhost); empty-string env var (PHOENIX_API_KEY="") which is falsy; passing the key under a different parameter name.

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

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

Appendix: source

Thrown at litellm/integrations/arize/arize_phoenix_client.py:42

    Supports:
    - Authentication with Bearer tokens
    - Fetching prompt versions
    - Direct API base URL configuration
    """

    def __init__(self, api_key: str | None = None, api_base: str | None = None):
        """
        Initialize the Arize Phoenix client.

        Args:
            api_key: Arize Phoenix API token
            api_base: Base URL for the Arize Phoenix API (e.g., 'https://app.phoenix.arize.com/s/workspace/v1')
        """
        self.api_key = api_key
        self.api_base = api_base

        if not self.api_key:
            raise ValueError("api_key is required")

        if not self.api_base:
            raise ValueError("api_base is required")

        # Set up authentication headers
        self.headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Accept": "application/json",
        }

        # Initialize HTTPHandler
        self.http_handler = HTTPHandler(disable_default_headers=True)

    def get_prompt_version(self, prompt_version_id: str) -> dict[str, Any] | None:
        """
        Fetch a prompt version from Arize Phoenix.

        Args:

View on GitHub (pinned to 77b7c6c40c)