BerriAI/litellm · error · ValueError

Unsupported guardrail: {guardrail_type}

Error message

Unsupported guardrail: {guardrail_type}

What it means

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>').

Source

Thrown at litellm/proxy/guardrails/guardrail_registry.py:503

            sig: Final = inspect.signature(initializer)
            if "llm_router" in sig.parameters:
                custom_guardrail_callback = initializer(
                    litellm_params,
                    guardrail,
                    llm_router,
                )
            else:
                custom_guardrail_callback = initializer(litellm_params, guardrail)
        elif isinstance(guardrail_type, str) and "." in guardrail_type:
            custom_guardrail_callback = self.initialize_custom_guardrail(
                guardrail=guardrail,
                guardrail_type=guardrail_type,
                litellm_params=litellm_params,
                config_file_path=config_file_path,
            )
        else:
            raise ValueError(f"Unsupported guardrail: {guardrail_type}")

        if custom_guardrail_callback is not None:
            for scoping_param in (
                "skip_system_message_in_guardrail",
                "skip_tool_message_in_guardrail",
                "scan_only_tool_results",
            ):
                setattr(custom_guardrail_callback, scoping_param, getattr(litellm_params, scoping_param, None))
            scan_only_tool_results_enabled: Final = effective_scan_only_tool_results_for_guardrail(
                custom_guardrail_callback
            )
            if scan_only_tool_results_enabled and not custom_guardrail_callback.supports_scan_only_tool_results():
                raise ValueError(
                    f"Guardrail {guardrail['guardrail_name']}: scan_only_tool_results is enabled, but this "
                    "guardrail's role filtering never scans tool results, so no request content would ever "
                    "be scanned. Remove scan_only_tool_results or the guardrail's role-filtering option."
                )
            if scan_only_tool_results_enabled and effective_skip_tool_message_for_guardrail(custom_guardrail_callback):

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Fix the spelling to a supported type - check litellm's guardrails docs for the exact registry key
2. Upgrade litellm if the guardrail is a newer integration
3. For custom guardrails use dotted module.Class syntax and ensure the module is importable from the proxy process
4. Check startup logs - litellm logs discovered initializer keys when scanning guardrail packages

Example fix

# before
litellm_params:
  guardrail: aim_security

# after (built-in type)
litellm_params:
  guardrail: aim

# after (custom guardrail)
litellm_params:
  guardrail: my_company.custom_guardrails.MyHandler

# Fail fast on unknown guardrail types at deploy time
import yaml
from litellm.proxy.guardrails.guardrail_registry import guardrail_initializer_registry

cfg = yaml.safe_load(open('config.yaml'))
for g in cfg.get('guardrails', []):
    gtype = (g.get('litellm_params') or {}).get('guardrail')
    if gtype and gtype not in guardrail_initializer_registry and '.' not in gtype:
        raise SystemExit(f'Unsupported guardrail: {gtype}. Fix the name or use module.Class for custom hooks.')

def is_supported_guardrail_type(gtype: str, registry_keys: set[str]) -> bool:
    """True for a registered built-in guardrail or a custom module.Class path."""
    return gtype in registry_keys or ('.' in gtype and gtype.split('.')[-1].isidentifier())

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• DynamoAI API key is required. Set DYNAMOAI_API_KEY environme
• EnkryptAI API key is required. Set ENKRYPTAI_API_KEY environ
• api_base is required for Generic Guardrail API. Set GENERIC_
• Gray Swan guardrail requires a guardrail_name
• llm_as_a_judge guardrail requires a guardrail_name

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