BerriAI/litellm · error · ValueError

OpenAI Moderation: guardrail_name is required

Error message

OpenAI Moderation: guardrail_name is required

What it means

Config-time ValueError from the openai (moderations) guardrail initializer: the guardrails list entry must carry a top-level 'guardrail_name' key, which LiteLLM uses to register and later reference the guardrail (e.g. guardrails: ["..."] on a model). Identical shape requirement to the Purview initializer — only the missing field differs.

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/openai/__init__.py:16

from typing import TYPE_CHECKING, Final

import litellm
from litellm.proxy.guardrails.guardrail_hooks.openai.moderations import (
    OpenAIModerationGuardrail,
)
from litellm.types.guardrails import SupportedGuardrailIntegrations

if TYPE_CHECKING:
    from litellm.types.guardrails import Guardrail, LitellmParams


def initialize_guardrail(litellm_params: "LitellmParams", guardrail: "Guardrail"):
    guardrail_name: Final = guardrail.get("guardrail_name")
    if not guardrail_name:
        raise ValueError("OpenAI Moderation: guardrail_name is required")

    optional_params: Final = getattr(litellm_params, "optional_params", None)

    openai_moderation_guardrail: Final = OpenAIModerationGuardrail(
        guardrail_name=guardrail_name,
        **{
            **litellm_params.model_dump(exclude_none=True),
            "api_key": litellm_params.api_key,
            "api_base": litellm_params.api_base,
            "default_on": litellm_params.default_on,
            "event_hook": litellm_params.mode,
            "model": litellm_params.model,
            "streaming_end_of_stream_only": _get_config_value(
                litellm_params, optional_params, "streaming_end_of_stream_only"
            ),
            "streaming_sampling_rate": _get_config_value(litellm_params, optional_params, "streaming_sampling_rate"),
        },
    )

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Add guardrail_name at the top level of the entry, next to litellm_params
2. Use a unique stable name, then reference it from deployments via guardrails: ["<name>"]
3. Restart the proxy

Example fix

# before
guardrails:
  - litellm_params:
      guardrail: openai_moderation
      mode: pre_call

# after
guardrails:
  - guardrail_name: oai-moderation
    litellm_params:
      guardrail: openai_moderation
      mode: pre_call

def guardrail_entries_valid(cfg: dict) -> list[str]:
    problems = []
    for i, g in enumerate(cfg.get("guardrails", [])):
        if not isinstance(g, dict) or not str(g.get("guardrail_name") or "").strip():
            problems.append(f"guardrails[{i}]: missing top-level guardrail_name")
    return problems

def is_named_guardrail_entry(x: object) -> bool:
    return isinstance(x, dict) and isinstance(x.get("guardrail_name"), str) and x["guardrail_name"].strip() != ""

When it happens

Trigger: Declaring litellm_params.guardrail: openai_moderation without a guardrail_name sibling key; nesting guardrail_name inside litellm_params; YAML indentation making the key a child of the wrong mapping

Common situations: First-time guardrail setup from memory; copy-paste from docs where the name line got dropped; refactoring config that lost the key

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Prisma client not initialized
• Guardrail configuration error: {init_error}
• Microsoft Purview: tenant_id is required
• Microsoft Purview: guardrail_name is required
• OpenAI Moderation: api_key is required. Set OPENAI_API_KEY e

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