{"record":{"id":"ebb46144a80d6893","repo":"BerriAI/litellm","slug":"unsupported-guardrail-guardrail-type","errorCode":null,"errorMessage":"Unsupported guardrail: {guardrail_type}","messagePattern":"Unsupported guardrail: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/proxy/guardrails/guardrail_registry.py","lineNumber":503,"sourceCode":"\n            sig: Final = inspect.signature(initializer)\n            if \"llm_router\" in sig.parameters:\n                custom_guardrail_callback = initializer(\n                    litellm_params,\n                    guardrail,\n                    llm_router,\n                )\n            else:\n                custom_guardrail_callback = initializer(litellm_params, guardrail)\n        elif isinstance(guardrail_type, str) and \".\" in guardrail_type:\n            custom_guardrail_callback = self.initialize_custom_guardrail(\n                guardrail=guardrail,\n                guardrail_type=guardrail_type,\n                litellm_params=litellm_params,\n                config_file_path=config_file_path,\n            )\n        else:\n            raise ValueError(f\"Unsupported guardrail: {guardrail_type}\")\n\n        if custom_guardrail_callback is not None:\n            for scoping_param in (\n                \"skip_system_message_in_guardrail\",\n                \"skip_tool_message_in_guardrail\",\n                \"scan_only_tool_results\",\n            ):\n                setattr(custom_guardrail_callback, scoping_param, getattr(litellm_params, scoping_param, None))\n            scan_only_tool_results_enabled: Final = effective_scan_only_tool_results_for_guardrail(\n                custom_guardrail_callback\n            )\n            if scan_only_tool_results_enabled and not custom_guardrail_callback.supports_scan_only_tool_results():\n                raise ValueError(\n                    f\"Guardrail {guardrail['guardrail_name']}: scan_only_tool_results is enabled, but this \"\n                    \"guardrail's role filtering never scans tool results, so no request content would ever \"\n                    \"be scanned. Remove scan_only_tool_results or the guardrail's role-filtering option.\"\n                )\n            if scan_only_tool_results_enabled and effective_skip_tool_message_for_guardrail(custom_guardrail_callback):","sourceCodeStart":485,"sourceCodeEnd":521,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/guardrails/guardrail_registry.py#L485-L521","documentation":"The guardrail type is looked up in guardrail_initializer_registry (built-in initializers plus auto-discovered hook packages). If the type is not registered AND does not contain a '.' (the marker for a custom guardrail path like my_pkg.MyHandler), initialization fails fast with ValueError('Unsupported guardrail: <type>').","triggerScenarios":"A typo in the guardrail value (e.g. 'aim_security' instead of 'aim'); using a guardrail integration that exists only in a newer litellm than the installed one; specifying a custom guardrail without module.Class dotted syntax or with a module not importable from the proxy's PYTHONPATH.","commonSituations":"Copy-pasting a guardrail name from docs for a different litellm version; OSS install missing an enterprise-only guardrail type; custom handler file not on the proxy's Python path.","solutions":["Fix the spelling to a supported type - check litellm's guardrails docs for the exact registry key","Upgrade litellm if the guardrail is a newer integration","For custom guardrails use dotted module.Class syntax and ensure the module is importable from the proxy process","Check startup logs - litellm logs discovered initializer keys when scanning guardrail packages"],"exampleFix":"# before\nlitellm_params:\n  guardrail: aim_security\n\n# after (built-in type)\nlitellm_params:\n  guardrail: aim\n\n# after (custom guardrail)\nlitellm_params:\n  guardrail: my_company.custom_guardrails.MyHandler","handlingStrategy":"validation","validationCode":"# Fail fast on unknown guardrail types at deploy time\nimport yaml\nfrom litellm.proxy.guardrails.guardrail_registry import guardrail_initializer_registry\n\ncfg = yaml.safe_load(open('config.yaml'))\nfor g in cfg.get('guardrails', []):\n    gtype = (g.get('litellm_params') or {}).get('guardrail')\n    if gtype and gtype not in guardrail_initializer_registry and '.' not in gtype:\n        raise SystemExit(f'Unsupported guardrail: {gtype}. Fix the name or use module.Class for custom hooks.')","typeGuard":"def is_supported_guardrail_type(gtype: str, registry_keys: set[str]) -> bool:\n    \"\"\"True for a registered built-in guardrail or a custom module.Class path.\"\"\"\n    return gtype in registry_keys or ('.' in gtype and gtype.split('.')[-1].isidentifier())","tryCatchPattern":null,"preventionTips":["Keep a pinned list of supported guardrail types per litellm version and validate configs against it","For custom guardrails, install the package in the proxy image and use full dotted paths","Upgrade litellm deliberately, then re-validate guardrail names against the new registry"],"tags":["guardrail","config","unsupported-type","startup"],"backgroundTag":"unsupported-guardrail-type","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}