BerriAI/litellm · error · ValueError

pattern_name is required for prebuilt patterns

Error message

pattern_name is required for prebuilt patterns

What it means

ValueError raised in ContentFilterGuardrail._add_pattern when a patterns[] config entry declares pattern_type: "prebuilt" but omits pattern_name. Prebuilt patterns are looked up by name via get_compiled_pattern(), so without a name the guardrail cannot know which regex (SSN, credit card, email, ...) to compile.

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py:738

        Returns:
            True if severity meets or exceeds threshold
        """
        severity_order: Final = {"low": 0, "medium": 1, "high": 2}
        return severity_order.get(severity, 0) >= severity_order.get(threshold, 1)

    def _add_pattern(self, pattern_config: ContentFilterPattern) -> None:
        """
        Add a pattern to the compiled patterns list.

        Args:
            pattern_config: ContentFilterPattern configuration
        """
        try:
            extra_config: _PatternExtraLookup = {"keyword_pattern": None, "allow_word_numbers": False}
            if pattern_config.pattern_type == "prebuilt":
                if not pattern_config.pattern_name:
                    raise ValueError("pattern_name is required for prebuilt patterns")
                compiled = get_compiled_pattern(pattern_config.pattern_name)
                pattern_name = pattern_config.pattern_name
                extra_config = self._lookup_pattern_extra(pattern_name)
            elif pattern_config.pattern_type == "regex":
                if not pattern_config.pattern:
                    raise ValueError("pattern is required for regex patterns")
                compiled = re.compile(pattern_config.pattern, re.IGNORECASE)
                pattern_name = pattern_config.name or "custom_regex"
            else:
                raise ValueError(f"Unknown pattern_type: {pattern_config.pattern_type}")

            keyword_pattern: Final = extra_config["keyword_pattern"]
            keyword_regex: Final = re.compile(keyword_pattern, re.IGNORECASE) if keyword_pattern else None

            self.compiled_patterns.append(
                {
                    "regex": compiled,
                    "pattern_name": pattern_name,

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Add pattern_name to the entry with a value from the prebuilt catalog (check get_compiled_pattern / the prebuilt registry for exact names, e.g. 'ssn', 'credit_card').
2. If you want a custom regex instead, switch the entry to pattern_type: regex and supply pattern.
3. Lint patterns at deploy time: prebuilt entries must have a non-empty pattern_name.
4. Confirm the name is not just present but spelled exactly as in the prebuilt catalog to avoid the next failure (unknown pattern lookup).

Example fix

# before
patterns:
  - pattern_type: prebuilt
    action: BLOCK

# after
patterns:
  - pattern_type: prebuilt
    pattern_name: ssn
    action: BLOCK

# Lint pattern entries: prebuilt requires pattern_name from the catalog
from litellm.proxy.guardrails.guardrail_hooks.litellm_content_filter.patterns import get_compiled_pattern  # adjust import to repo

def lint_patterns(patterns: list[dict]) -> list[str]:
    problems = []
    for p in patterns:
        if p.get("pattern_type") == "prebuilt" and not p.get("pattern_name"):
            problems.append(f"prebuilt pattern missing pattern_name: {p}")
    return problems

from typing import TypedDict, Literal

class PrebuiltPattern(TypedDict):
    pattern_type: Literal["prebuilt"]
    pattern_name: str
    action: str

def is_valid_prebuilt(entry: dict) -> bool:
    return (
        entry.get("pattern_type") == "prebuilt"
        and isinstance(entry.get("pattern_name"), str)
        and bool(entry["pattern_name"].strip())
    )

When it happens

Trigger: Config yaml contains litellm_params.patterns with an entry like {pattern_type: prebuilt, action: BLOCK} that lacks pattern_name, and the guardrail initialization loop calls _add_pattern on it.

Common situations: Copied example config with the placeholder name deleted; assumption that the generic `name` field selects the prebuilt pattern; refactoring that renamed/dropped the field.

Related errors

• pattern is required for regex patterns
• Content Filter: guardrail_name is required
• Unknown pattern_type: {pattern_config.pattern_type}
• Invalid format: file must contain 'blocked_words' key with l
• Error loading blocked words file {file_path}: {e}

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