BerriAI/litellm · error · ValueError

Content Filter: guardrail_name is required

Error message

Content Filter: guardrail_name is required

What it means

ValueError raised by the content-filter guardrail's instantiate() factory when the guardrail entry's metadata dict has no guardrail_name. Every litellm guardrail needs a unique name for lookup, logging, and per-guardrail routing, so the factory refuses to construct ContentFilterGuardrail without one.

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/__init__.py:32

def initialize_guardrail(
    litellm_params: "LitellmParams",
    guardrail: "Guardrail",
    llm_router: Optional["Router"] = None,
):
    """
    Initialize the Content Filter Guardrail.

    Args:
        litellm_params: Guardrail configuration parameters
        guardrail: Guardrail metadata

    Returns:
        Initialized ContentFilterGuardrail instance
    """
    guardrail_name: Final = guardrail.get("guardrail_name")

    if not guardrail_name:
        raise ValueError("Content Filter: guardrail_name is required")

    content_filter_guardrail: Final = ContentFilterGuardrail(
        guardrail_name=guardrail_name,
        guardrail_id=guardrail.get("guardrail_id"),
        policy_template=guardrail.get("policy_template"),
        patterns=litellm_params.patterns,
        blocked_words=litellm_params.blocked_words,
        blocked_words_file=litellm_params.blocked_words_file,
        event_hook=litellm_params.mode,
        default_on=litellm_params.default_on or False,
        categories=getattr(litellm_params, "categories", None),
        severity_threshold=getattr(litellm_params, "severity_threshold", "medium"),
        llm_router=llm_router,
        image_model=getattr(litellm_params, "image_model", None),
        competitor_intent_config=getattr(litellm_params, "competitor_intent_config", None),
        end_session_after_n_fails=getattr(litellm_params, "end_session_after_n_fails", None),
        on_violation=getattr(litellm_params, "on_violation", None),
        realtime_violation_message=getattr(litellm_params, "realtime_violation_message", None),

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Add guardrail_name: <unique-name> at the guardrail entry level (sibling of litellm_params, not inside it).
2. Check YAML indentation — guardrail_name must sit next to litellm_params for the same list item.
3. Lint the config before deploy: assert every entry under guardrails has a non-empty guardrail_name.
4. If registering programmatically, include 'guardrail_name' in the guardrail metadata dict passed to the factory.

Example fix

# before
litellm_settings:
  guardrails:
    - litellm_params:
        guardrail: litellm_content_filter
        mode: pre_call

# after
litellm_settings:
  guardrails:
    - guardrail_name: my-content-filter
      litellm_params:
        guardrail: litellm_content_filter
        mode: pre_call

# Config lint: every guardrail entry needs a non-empty guardrail_name
import yaml

def lint_guardrail_names(path: str = "config.yaml") -> list[str]:
    cfg = yaml.safe_load(open(path))
    problems = []
    for g in cfg.get("litellm_settings", {}).get("guardrails", []):
        if not g.get("guardrail_name"):
            problems.append(f"guardrail entry missing guardrail_name: {g}")
    return problems

# assert not lint_guardrail_names() in CI

from typing import Any

def is_valid_guardrail_entry(entry: Any) -> bool:
    """Narrow a parsed YAML guardrail entry to a well-formed one."""
    return (
        isinstance(entry, dict)
        and isinstance(entry.get("guardrail_name"), str)
        and bool(entry["guardrail_name"].strip())
        and isinstance(entry.get("litellm_params"), dict)
    )

When it happens

Trigger: The proxy loads a guardrails entry whose litellm_params configure the content filter, but the entry itself lacks a guardrail_name key (or it is None/empty) at guardrail-definition load time.

Common situations: A YAML entry with a typo (guardrail-name, name) or the field accidentally nested under litellm_params; a copy-pasted example config with the name stripped out; programmatic guardrail registration that passes only litellm_params.

Related errors

• Guardrail configuration error: {init_error}
• Cisco AI Defense guardrail: invalid rule definition: {rule!r
• max_bytes_per_call must be >= 0 (0 disables the cap; positiv
• pattern_name is required for prebuilt patterns
• pattern is required for regex patterns

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