BerriAI/litellm · error · Exception

DD_API_KEY is not set, set 'DD_API_KEY=<'

Error message

DD_API_KEY is not set, set 'DD_API_KEY=<'

What it means

DataDogLLMObsLogger.__init__ decides between two modes: agent mode (LITELLM_DD_AGENT_HOST set, no API key needed) and direct-API mode. In direct mode both DD_API_KEY and DD_SITE must be present in the environment; a missing DD_API_KEY raises this Exception during construction. Because custom loggers are instantiated when callbacks load (e.g. at proxy startup), this error typically aborts startup.

Source

Thrown at litellm/integrations/datadog/datadog_llm_obs.py:71

            if self.is_mock_mode:
                create_mock_datadog_client()
                verbose_logger.debug("[DATADOG MOCK] DataDogLLMObs logger initialized in mock mode")

            # Configure DataDog endpoint (Agent or Direct API)
            # Use LITELLM_DD_AGENT_HOST to avoid conflicts with ddtrace's DD_AGENT_HOST
            # Check for agent mode FIRST - agent mode doesn't require DD_API_KEY or DD_SITE
            dd_agent_host: Final = os.getenv("LITELLM_DD_AGENT_HOST")

            self.async_client = get_async_httpx_client(llm_provider=httpxSpecialProvider.LoggingCallback)
            self.DD_API_KEY = os.getenv("DD_API_KEY")

            if dd_agent_host:
                self._configure_dd_agent(dd_agent_host=dd_agent_host)
            else:
                # Only require DD_API_KEY and DD_SITE for direct API mode
                if os.getenv("DD_API_KEY", None) is None:
                    raise Exception("DD_API_KEY is not set, set 'DD_API_KEY=<>'")
                if os.getenv("DD_SITE", None) is None:
                    raise Exception("DD_SITE is not set, set 'DD_SITE=<>', example sit = `us5.datadoghq.com`")
                self._configure_dd_direct_api()

            # Optional override for testing
            dd_base_url: Final = get_datadog_base_url_from_env()
            if dd_base_url:
                self.intake_url = f"{dd_base_url}/api/intake/llm-obs/v1/trace/spans"

            asyncio.create_task(self.periodic_flush())
            self.flush_lock = asyncio.Lock()
            self.log_queue: list[LLMObsPayload] = []

            #########################################################
            # Handle datadog_llm_observability_params set as litellm.datadog_llm_observability_params
            #########################################################
            dict_datadog_llm_obs_params: Final = self._get_datadog_llm_obs_params()
            kwargs.update(dict_datadog_llm_obs_params)

View on GitHub (pinned to 77b7c6c40c)

Solutions

  1. Export DD_API_KEY in the environment of the process running litellm (docker-compose env:, systemd Environment=, k8s secret) and confirm with printenv | grep DD_
  2. If you meant to ship via the Datadog agent, set LITELLM_DD_AGENT_HOST instead — agent mode skips the key requirement entirely
  3. Double-check the exact variable name is DD_API_KEY, not DATADOG_API_KEY

Example fix

# before (container starts without secrets)
docker run my-proxy  # Exception: DD_API_KEY is not set

# after
docker run -e DD_API_KEY=$DD_API_KEY -e DD_SITE=us5.datadoghq.com my-proxy
Defensive patterns

Strategy: validation

Validate before calling

import os

def can_enable_datadog_llm_obs() -> bool:
    """Direct mode needs DD_API_KEY+DD_SITE; agent mode needs LITELLM_DD_AGENT_HOST."""
    if os.getenv("LITELLM_DD_AGENT_HOST"):
        return True
    return bool(os.getenv("DD_API_KEY")) and bool(os.getenv("DD_SITE"))

# in config:
# callbacks = [DataDogLLMObsLogger()] if can_enable_datadog_llm_obs() else []

Prevention

When it happens

Trigger: Configuring callbacks: ["datadog_llm_obs"] in litellm_settings without DD_API_KEY exported; intending agent mode but typo-ing LITELLM_DD_AGENT_HOST so the code falls through to the direct-API branch; running in CI/docker where the secret was never injected.

Common situations: Env var set in an interactive shell but not in the systemd unit / docker-compose / k8s deployment; key stored under a different name (DATADOG_API_KEY, DD_API_KEY_2); .env file not loaded by the service.

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/5d76712833c9b395. Report an issue: GitHub.