BerriAI/litellm · error · ValueError

guardrail_type is required

Error message

guardrail_type is required

What it means

When initializing a guardrail, litellm reads the guardrail type from litellm_params.guardrail and looks it up in the initializer registry. If that key is absent or None, no initializer can be selected and ValueError('guardrail_type is required') is raised at proxy startup or guardrail creation time.

Source

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

        if isinstance(litellm_params_data, dict):
            litellm_params = LitellmParams(**litellm_params_data)
        else:
            litellm_params = litellm_params_data

        if "category_thresholds" in litellm_params_data and litellm_params_data["category_thresholds"]:
            lakera_category_thresholds: Final = LakeraCategoryThresholds(**litellm_params_data["category_thresholds"])
            litellm_params.category_thresholds = lakera_category_thresholds

        if litellm_params.api_key and litellm_params.api_key.startswith("os.environ/"):
            litellm_params.api_key = str(get_secret(litellm_params.api_key))

        if litellm_params.api_base and litellm_params.api_base.startswith("os.environ/"):
            litellm_params.api_base = str(get_secret(litellm_params.api_base))

        guardrail_type: Final = litellm_params.guardrail

        if guardrail_type is None:
            raise ValueError("guardrail_type is required")

        initializer: Final = guardrail_initializer_registry.get(guardrail_type)

        if initializer:
            # Try to call with llm_router first, fall back to without if it fails
            import inspect

            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(

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Add guardrail: <type> (e.g. aim, bedrock, hide_secrets) inside litellm_params
2. Check YAML indentation - keys like guardrail, mode, api_key must sit under litellm_params
3. Validate the guardrails block against litellm's documented config schema before restarting

Example fix

# before
guardrails:
  - guardrail_name: my-guardrail
    litellm_params:
      mode: pre_call

# after
guardrails:
  - guardrail_name: my-guardrail
    litellm_params:
      guardrail: aim
      mode: pre_call

# Lint guardrail config before startup
import yaml

cfg = yaml.safe_load(open('config.yaml'))
for g in cfg.get('guardrails', []):
    lp = g.get('litellm_params') or {}
    if not lp.get('guardrail'):
        raise SystemExit(f"guardrail '{g.get('guardrail_name')}' missing litellm_params.guardrail")

from typing import Any

def is_complete_guardrail_entry(entry: dict[str, Any]) -> bool:
    """True when a guardrails entry names itself and declares a guardrail type."""
    return (
        isinstance(entry.get('guardrail_name'), str)
        and bool((entry.get('litellm_params') or {}).get('guardrail'))
    )

When it happens

Trigger: A guardrails config entry whose litellm_params block is missing the guardrail key (e.g. only mode/default_on set), or a /guardrails/create API call whose litellm_params omits it.

Common situations: YAML indentation mistake putting guardrail at the entry top level instead of under litellm_params; hand-written config missing the type key; guardrail created programmatically without the field.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

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/ad03e78c5f54d219. Report an issue: GitHub.