{"record":{"id":"df4744c9752140e0","repo":"BerriAI/litellm","slug":"onyx-api-key-environment-variable-is-not-set","errorCode":null,"errorMessage":"ONYX_API_KEY environment variable is not set","messagePattern":"ONYX_API_KEY environment variable is not set","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/proxy/guardrails/guardrail_hooks/onyx/onyx.py","lineNumber":59,"sourceCode":"        self,\n        api_base: str | None = None,\n        api_key: str | None = None,\n        timeout: float | None = 10.0,\n        **kwargs,\n    ):\n        kwargs.setdefault(\"supported_event_hooks\", list(self.get_supported_event_hooks()))\n        timeout = timeout or int(os.getenv(\"ONYX_TIMEOUT\", 10.0))\n        self.async_handler = get_async_httpx_client(\n            llm_provider=httpxSpecialProvider.GuardrailCallback,\n            params={\"timeout\": httpx.Timeout(timeout=timeout, connect=5.0)},\n        )\n        self.api_base = api_base or os.getenv(\n            \"ONYX_API_BASE\",\n            \"https://ai-guard.onyx.security\",\n        )\n        self.api_key = api_key or os.getenv(\"ONYX_API_KEY\")\n        if not self.api_key:\n            raise ValueError(\"ONYX_API_KEY environment variable is not set\")\n        self.optional_params = kwargs\n        super().__init__(**kwargs)\n        verbose_proxy_logger.info(\"OnyxGuard initialized with server: %s\", self.api_base)\n\n    async def _validate_with_guard_server(\n        self,\n        payload: Any,\n        input_type: Literal[\"request\", \"response\"],\n        conversation_id: str,\n    ) -> dict:\n        \"\"\"\n        Call external Onyx Guard server for validation\n        \"\"\"\n        response: Final = await self.async_handler.post(\n            f\"{self.api_base}/guard/evaluate/v1/{self.api_key}/litellm\",\n            json={\n                \"payload\": payload,\n                \"input_type\": input_type,","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/guardrails/guardrail_hooks/onyx/onyx.py#L41-L77","documentation":"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.","triggerScenarios":"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)","commonSituations":"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","solutions":["Export ONYX_API_KEY in the environment the proxy actually runs in (ENV in Dockerfile, env in compose, secret in k8s)","Or pass api_key directly under litellm_params in the guardrail config if you prefer config-based secrets","Verify with a printenv ONYX_API_KEY inside the same execution context, then restart the proxy"],"exampleFix":"# before (docker-compose, key missing)\nservices:\n  litellm:\n    image: ghcr.io/berriai/litellm\n\n# after\nservices:\n  litellm:\n    image: ghcr.io/berriai/litellm\n    environment:\n      - ONYX_API_KEY=${ONYX_API_KEY}\n      # optionally: ONYX_API_BASE=https://guard.internal.corp","handlingStrategy":"validation","validationCode":"import os\n\nmissing = [v for v in (\"ONYX_API_KEY\",) if not os.getenv(v)]\nif missing:\n    raise SystemExit(f\"cannot start proxy; missing env: {missing}\")\n# optionally also ONYX_API_BASE if self-hosted","typeGuard":null,"tryCatchPattern":"try:\n    from litellm.proxy.guardrails.guardrail_hooks.onyx.onyx import OnyxGuard\n    guard = OnyxGuard(guardrail_name=\"onyx\", **lp)\nexcept ValueError as e:\n    if \"ONYX_API_KEY\" in str(e):\n        load_secrets_and_retry_once()  # e.g. late-mounted secret file\n    else:\n        raise","preventionTips":["Declare Onyx secrets as hard dependencies (required env in compose/k8s) so the pod fails before serving traffic","Use init containers or entrypoint checks that verify all guardrail env vars before the proxy starts"],"tags":["onyx","guardrails","environment-variables","secrets","configuration"],"backgroundTag":"missing-env-var","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}