BerriAI/litellm · error · ValueError

ONYX_API_KEY environment variable is not set

Error message

ONYX_API_KEY environment variable is not set

What it means

Init-time ValueError from OnyxGuard.__init__. The Onyx guardrail talks to an Onyx Guard server (default https://ai-guard.onyx.security) and requires an API key; it reads api_key from the guardrail config first and falls back to the ONYX_API_KEY environment variable. If neither is present the guardrail fails to construct, aborting proxy startup or guardrail registration.

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/onyx/onyx.py:59

        self,
        api_base: str | None = None,
        api_key: str | None = None,
        timeout: float | None = 10.0,
        **kwargs,
    ):
        kwargs.setdefault("supported_event_hooks", list(self.get_supported_event_hooks()))
        timeout = timeout or int(os.getenv("ONYX_TIMEOUT", 10.0))
        self.async_handler = get_async_httpx_client(
            llm_provider=httpxSpecialProvider.GuardrailCallback,
            params={"timeout": httpx.Timeout(timeout=timeout, connect=5.0)},
        )
        self.api_base = api_base or os.getenv(
            "ONYX_API_BASE",
            "https://ai-guard.onyx.security",
        )
        self.api_key = api_key or os.getenv("ONYX_API_KEY")
        if not self.api_key:
            raise ValueError("ONYX_API_KEY environment variable is not set")
        self.optional_params = kwargs
        super().__init__(**kwargs)
        verbose_proxy_logger.info("OnyxGuard initialized with server: %s", self.api_base)

    async def _validate_with_guard_server(
        self,
        payload: Any,
        input_type: Literal["request", "response"],
        conversation_id: str,
    ) -> dict:
        """
        Call external Onyx Guard server for validation
        """
        response: Final = await self.async_handler.post(
            f"{self.api_base}/guard/evaluate/v1/{self.api_key}/litellm",
            json={
                "payload": payload,
                "input_type": input_type,

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Export ONYX_API_KEY in the environment the proxy actually runs in (ENV in Dockerfile, env in compose, secret in k8s)
2. Or pass api_key directly under litellm_params in the guardrail config if you prefer config-based secrets
3. Verify with a printenv ONYX_API_KEY inside the same execution context, then restart the proxy

Example fix

# before (docker-compose, key missing)
services:
  litellm:
    image: ghcr.io/berriai/litellm

# after
services:
  litellm:
    image: ghcr.io/berriai/litellm
    environment:
      - ONYX_API_KEY=${ONYX_API_KEY}
      # optionally: ONYX_API_BASE=https://guard.internal.corp

import os

missing = [v for v in ("ONYX_API_KEY",) if not os.getenv(v)]
if missing:
    raise SystemExit(f"cannot start proxy; missing env: {missing}")
# optionally also ONYX_API_BASE if self-hosted

try:
    from litellm.proxy.guardrails.guardrail_hooks.onyx.onyx import OnyxGuard
    guard = OnyxGuard(guardrail_name="onyx", **lp)
except ValueError as e:
    if "ONYX_API_KEY" in str(e):
        load_secrets_and_retry_once()  # e.g. late-mounted secret file
    else:
        raise

When it happens

Trigger: Adding a guardrails entry with guardrail: onyx while ONYX_API_KEY is not exported in the proxy process's environment; env var set in a shell but the proxy runs under systemd/docker where it is missing; empty-string ONYX_API_KEY="" (falsy)

Common situations: Container/k8s deployments forgetting to add the secret to the pod spec; CI pipelines starting the proxy without sourcing the secrets file; rotating to a new Onyx instance and dropping the env wiring

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

• Missing Ovalix guardrail configuration errors: {errors}
• Microsoft Purview: client_secret (or api_key) is required
• OpenAI Moderation: api_key is required. Set OPENAI_API_KEY e
• Either 'REDIS_URL' or both 'REDIS_HOST' and 'REDIS_PORT' mus
• REDIS_CLUSTER_NODES environment variable is not valid JSON.

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