{"record":{"id":"da20b7294c3014be","repo":"BerriAI/litellm","slug":"guardrail-self-guardrail-name-or-type-self-nam","errorCode":null,"errorMessage":"Guardrail {self.guardrail_name or type(self).__name__} implements apply_guardrail, which needs the litellm proxy dependencies to run at the deployment level. Install them with: pip install 'litellm[proxy]'","messagePattern":"Guardrail (.+?) implements apply_guardrail, which needs the litellm proxy dependencies to run at the deployment level\\. Install them with: pip install 'litellm\\[proxy\\]'","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"litellm/integrations/custom_guardrail.py","lineNumber":640,"sourceCode":"            return False\n        for meta_key in (\"metadata\", \"litellm_metadata\"):\n            meta = data.get(meta_key)\n            if isinstance(meta, dict):\n                executed = meta.get(PRE_CALL_EXECUTED_GUARDRAILS_KEY)\n                if isinstance(executed, list) and marker in executed:\n                    return True\n        return False\n\n    def uses_apply_guardrail_interface(self) -> bool:\n        return type(self).apply_guardrail is not CustomGuardrail.apply_guardrail\n\n    def _deployment_pre_call_target(self) -> \"CustomLogger\":\n        if not self.uses_apply_guardrail_interface():\n            return self\n        try:\n            from litellm.proxy.utils import unified_guardrail\n        except ImportError as e:\n            raise ImportError(\n                f\"Guardrail {self.guardrail_name or type(self).__name__} implements apply_guardrail, which needs \"\n                \"the litellm proxy dependencies to run at the deployment level. \"\n                \"Install them with: pip install 'litellm[proxy]'\"\n            ) from e\n        return unified_guardrail\n\n    async def async_pre_call_deployment_hook(self, kwargs: dict[str, Any], call_type: CallTypes | None) -> dict | None:\n        from litellm.proxy._types import UserAPIKeyAuth\n\n        # should run guardrail\n        litellm_guardrails: Final = kwargs.get(\"guardrails\")\n        if litellm_guardrails is None or not isinstance(litellm_guardrails, list):\n            return kwargs\n\n        if self._pre_call_hook_already_ran(kwargs):\n            return kwargs\n\n        if self.should_run_guardrail(data=kwargs, event_type=GuardrailEventHooks.pre_call) is not True:","sourceCodeStart":622,"sourceCodeEnd":658,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/integrations/custom_guardrail.py#L622-L658","documentation":"A guardrail subclass overrides apply_guardrail(), so at deployment level the proxy must wrap it with litellm.proxy.utils.unified_guardrail. When that import fails, litellm knows the optional proxy dependencies are missing and raises ImportError telling you to install the 'proxy' extra. It is a packaging error, not a logic error in your guardrail.","triggerScenarios":"Using litellm installed as the slim/core package (pip install litellm without extras, or a lambda/docker image built from requirements listing bare litellm) and loading a guardrail that implements apply_guardrail via _deployment_pre_call_target(). The try-import of litellm.proxy.utils fails because fastapi & co. are absent.","commonSituations":"SDK-only installs later pointed at proxy-style guardrail configs; minimal Docker images that strip extras to reduce size; CI environments installing litellm from a lockfile pinned to the base wheel.","solutions":["Install the proxy extras: pip install 'litellm[proxy]'","If you run the official litellm proxy image, ensure your custom Dockerfile does not downgrade litellm to the base wheel","If apply_guardrail is not needed, remove the override so the guardrail uses hook-based methods and the proxy dependency is not required"],"exampleFix":"# before\npip install litellm\n\n# after\npip install 'litellm[proxy]'","handlingStrategy":"validation","validationCode":"def proxy_deps_available() -> bool:\n    try:\n        import litellm.proxy.utils  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nif guardrail.uses_apply_guardrail_interface() and not proxy_deps_available():\n    raise SystemExit(\"Install with: pip install 'litellm[proxy]'\")","typeGuard":null,"tryCatchPattern":"try:\n    _ = guardrail._deployment_pre_call_target()\nexcept ImportError as e:\n    if \"litellm[proxy]\" in str(e):\n        subprocess.check_call([pip, \"install\", \"litellm[proxy]\"])  # then restart\n    raise","preventionTips":["Pin 'litellm[proxy]' (not bare litellm) in requirements for proxy deployments","Add a startup smoke test that imports litellm.proxy.utils when apply_guardrail guardrails are configured","In Dockerfiles, prefer the official litellm proxy image as the base"],"tags":["packaging","import-error","guardrail","dependencies"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}