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 supports two transports: an agent mode enabled by LITELLM_DD_AGENT_HOST (no credentials needed) and direct-API mode. When no agent host is configured, __init__ requires DD_API_KEY from the environment and raises this Exception if it is unset. This guards the LLM Observability trace intake, separate from the plain Datadog logs integration.

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 6c2dcb801b)

Solutions

  1. Set DD_API_KEY (and DD_SITE) for direct API mode
  2. Or set LITELLM_DD_AGENT_HOST to point at your Datadog agent, which bypasses the API-key requirement
  3. Double-check you used LITELLM_DD_AGENT_HOST, not DD_AGENT_HOST — litellm intentionally uses a different name to avoid ddtrace conflicts

Example fix

# before
# only DD_AGENT_HOST=localhost set -> direct mode -> raises

# after (agent mode)
export LITELLM_DD_AGENT_HOST=localhost
# or (direct mode)
export DD_API_KEY=xxx
export DD_SITE=us5.datadoghq.com
Defensive patterns

Strategy: validation

Validate before calling

import os

def llm_obs_ready() -> bool:
    return bool(os.getenv("LITELLM_DD_AGENT_HOST")) or bool(os.getenv("DD_API_KEY"))

assert llm_obs_ready(), "set LITELLM_DD_AGENT_HOST (agent) or DD_API_KEY (direct)"

Try / catch

try:
    DataDogLLMObsLogger()
except Exception as e:
    if "DD_API_KEY" in str(e):
        configure_agent_mode()  # or set the env var and restart
    raise

Prevention

When it happens

Trigger: Constructing DataDogLLMObsLogger with LITELLM_DD_AGENT_HOST unset and DD_API_KEY missing from the environment (os.getenv('DD_API_KEY', None) is None). Set LITELLM_DD_AGENT_HOST and the check is skipped entirely.

Common situations: Enabling datadog_llm_observability in proxy config without provisioning env vars; intending to use a local Datadog agent but setting DD_AGENT_HOST (the ddtrace variable) instead of LITELLM_DD_AGENT_HOST, so agent mode is not detected.

Related errors

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/a0764a1292cce153. Report an issue: GitHub.