{"record":{"id":"bf6a603a85726951","repo":"BerriAI/litellm","slug":"missing-ovalix-guardrail-configuration-errors-er","errorCode":null,"errorMessage":"Missing Ovalix guardrail configuration errors: {errors}","messagePattern":"Missing Ovalix guardrail configuration errors: (.+?)","errorType":"validation","errorClass":"OvalixGuardrailMissingSecrets","httpStatus":null,"severity":"error","filePath":"litellm/proxy/guardrails/guardrail_hooks/ovalix/ovalix.py","lineNumber":133,"sourceCode":"        errors: Final[list[str]] = []\n\n        if not self._tracker_api_base:\n            errors.append(\"Tracker API base, set OVALIX_TRACKER_API_BASE or pass tracker_api_base\")\n        if not self._tracker_api_key:\n            errors.append(\"Tracker API key, set OVALIX_TRACKER_API_KEY or pass tracker_api_key\")\n        if not self._application_id:\n            errors.append(\"Application ID, set OVALIX_APPLICATION_ID or pass application_id\")\n        if not self._pre_checkpoint_id and GuardrailEventHooks.pre_call in supported_event_hooks:\n            errors.append(\"Pre-checkpoint ID, set OVALIX_PRE_CHECKPOINT_ID or pass pre_checkpoint_id\")\n        if not self._post_checkpoint_id and GuardrailEventHooks.post_call in supported_event_hooks:\n            errors.append(\"Post-checkpoint ID, set OVALIX_POST_CHECKPOINT_ID or pass post_checkpoint_id\")\n        if not self._pre_checkpoint_id and not self._post_checkpoint_id:\n            errors.append(\n                \"Pre-checkpoint ID or Post-checkpoint ID, set OVALIX_PRE_CHECKPOINT_ID or OVALIX_POST_CHECKPOINT_ID or pass pre_checkpoint_id or post_checkpoint_id\"\n            )\n\n        if errors:\n            raise OvalixGuardrailMissingSecrets(\"Missing Ovalix guardrail configuration errors: \" + \". \".join(errors))\n\n        # auto-add hooks when checkpoint IDs are present\n        if self._pre_checkpoint_id and GuardrailEventHooks.pre_call not in supported_event_hooks:\n            supported_event_hooks.append(GuardrailEventHooks.pre_call)\n        if self._post_checkpoint_id and GuardrailEventHooks.post_call not in supported_event_hooks:\n            supported_event_hooks.append(GuardrailEventHooks.post_call)\n\n    def _get_actor(self, data: dict) -> str:\n        \"\"\"Return a stable actor identifier from request metadata (e.g. user email or id).\"\"\"\n        metadata: Final = data.get(\"metadata\") or data.get(\"litellm_metadata\") or {}\n        if metadata.get(\"user_api_key_user_email\"):\n            return metadata[\"user_api_key_user_email\"]\n        if metadata.get(\"user_api_key_user_id\"):\n            return metadata[\"user_api_key_user_id\"]\n        return \"unknown\"\n\n    def _get_tracker_actor_id(self, data: dict) -> str:\n        \"\"\"Normalize the actor string into a short, stable id for Tracker API payloads.\"\"\"","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/guardrails/guardrail_hooks/ovalix/ovalix.py#L115-L151","documentation":"Init-time OvalixGuardrailMissingSecrets (custom Exception subclass) from OvalixGuardrail._validate_config. It aggregates every missing required setting into one message: OVALIX_APPLICATION_ID (always required), OVALIX_PRE_CHECKPOINT_ID (required only when the pre_call hook is enabled), OVALIX_POST_CHECKPOINT_ID (required only when post_call is enabled), plus a combined error when neither checkpoint id exists. Values come from env vars or constructor params.","triggerScenarios":"Configuring guardrail: ovalix without any OVALIX_* env vars; enabling mode: pre_call but providing only the post checkpoint id; empty-string env values counting as missing; deploying the proxy in an environment where the Ovalix secrets were never injected","commonSituations":"K8s/compose deployments missing the Ovalix secret mounts; enabling an extra event hook (e.g. adding post_call for output scanning) without also adding OVALIX_POST_CHECKPOINT_ID; local dev with a partial .env","solutions":["Read the message — it lists exactly which pieces are missing and which env var or param supplies each","Set OVALIX_APPLICATION_ID plus the checkpoint id(s) matching the hooks you enabled (or pass application_id/pre_checkpoint_id/post_checkpoint_id in litellm_params)","If you only need one direction of checking, restrict supported hooks/mode so only the matching checkpoint id is required","Restart the proxy after the secrets are present"],"exampleFix":"# before\nenvironment:\n  - OVALIX_APPLICATION_ID=app_123\n\n# after\nenvironment:\n  - OVALIX_APPLICATION_ID=app_123\n  - OVALIX_PRE_CHECKPOINT_ID=chk_pre_456\n  - OVALIX_POST_CHECKPOINT_ID=chk_post_789","handlingStrategy":"validation","validationCode":"import os\n\nrequired_always = [\"OVALIX_APPLICATION_ID\"]\nhooks = set(cfg_guardrail.get(\"supported_event_hooks\", []))\nneed = list(required_always)\nif \"pre_call\" in hooks or cfg_guardrail.get(\"mode\") == \"pre_call\":\n    need.append(\"OVALIX_PRE_CHECKPOINT_ID\")\nif \"post_call\" in hooks or cfg_guardrail.get(\"mode\") == \"post_call\":\n    need.append(\"OVALIX_POST_CHECKPOINT_ID\")\n\nmissing = [v for v in need if not os.getenv(v)]\nassert not missing, f\"missing Ovalix env: {missing}\"","typeGuard":null,"tryCatchPattern":"try:\n    from litellm.proxy.guardrails.guardrail_hooks.ovalix.ovalix import OvalixGuard\n    guard = OvalixGuard(guardrail_name=\"ovalix\", **lp)\nexcept Exception as e:  # OvalixGuardrailMissingSecrets subclasses Exception\n    if \"Missing Ovalix guardrail configuration\" in str(e):\n        fail_deploy(str(e))  # message already itemizes what is missing\n    raise","preventionTips":["Model the hook->checkpoint-id dependency in your deployment checklist: each enabled mode needs its id","Mount Ovalix secrets as required env in the deployment spec, not optional","Test config changes on staging where the guardrail actually initializes"],"tags":["ovalix","guardrails","environment-variables","secrets","configuration"],"backgroundTag":"missing-required-config","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}