{"record":{"id":"b88b3f7c7680f863","repo":"BerriAI/litellm","slug":"openai-moderation-guardrail-name-is-required","errorCode":null,"errorMessage":"OpenAI Moderation: guardrail_name is required","messagePattern":"OpenAI Moderation: guardrail_name is required","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/proxy/guardrails/guardrail_hooks/openai/__init__.py","lineNumber":16,"sourceCode":"from typing import TYPE_CHECKING, Final\n\nimport litellm\nfrom litellm.proxy.guardrails.guardrail_hooks.openai.moderations import (\n    OpenAIModerationGuardrail,\n)\nfrom litellm.types.guardrails import SupportedGuardrailIntegrations\n\nif TYPE_CHECKING:\n    from litellm.types.guardrails import Guardrail, LitellmParams\n\n\ndef initialize_guardrail(litellm_params: \"LitellmParams\", guardrail: \"Guardrail\"):\n    guardrail_name: Final = guardrail.get(\"guardrail_name\")\n    if not guardrail_name:\n        raise ValueError(\"OpenAI Moderation: guardrail_name is required\")\n\n    optional_params: Final = getattr(litellm_params, \"optional_params\", None)\n\n    openai_moderation_guardrail: Final = OpenAIModerationGuardrail(\n        guardrail_name=guardrail_name,\n        **{\n            **litellm_params.model_dump(exclude_none=True),\n            \"api_key\": litellm_params.api_key,\n            \"api_base\": litellm_params.api_base,\n            \"default_on\": litellm_params.default_on,\n            \"event_hook\": litellm_params.mode,\n            \"model\": litellm_params.model,\n            \"streaming_end_of_stream_only\": _get_config_value(\n                litellm_params, optional_params, \"streaming_end_of_stream_only\"\n            ),\n            \"streaming_sampling_rate\": _get_config_value(litellm_params, optional_params, \"streaming_sampling_rate\"),\n        },\n    )","sourceCodeStart":1,"sourceCodeEnd":34,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/guardrails/guardrail_hooks/openai/__init__.py#L1-L34","documentation":"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.","triggerScenarios":"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","commonSituations":"First-time guardrail setup from memory; copy-paste from docs where the name line got dropped; refactoring config that lost the key","solutions":["Add guardrail_name at the top level of the entry, next to litellm_params","Use a unique stable name, then reference it from deployments via guardrails: [\"<name>\"]","Restart the proxy"],"exampleFix":"# before\nguardrails:\n  - litellm_params:\n      guardrail: openai_moderation\n      mode: pre_call\n\n# after\nguardrails:\n  - guardrail_name: oai-moderation\n    litellm_params:\n      guardrail: openai_moderation\n      mode: pre_call","handlingStrategy":"validation","validationCode":"def guardrail_entries_valid(cfg: dict) -> list[str]:\n    problems = []\n    for i, g in enumerate(cfg.get(\"guardrails\", [])):\n        if not isinstance(g, dict) or not str(g.get(\"guardrail_name\") or \"\").strip():\n            problems.append(f\"guardrails[{i}]: missing top-level guardrail_name\")\n    return problems","typeGuard":"def is_named_guardrail_entry(x: object) -> bool:\n    return isinstance(x, dict) and isinstance(x.get(\"guardrail_name\"), str) and x[\"guardrail_name\"].strip() != \"\"","tryCatchPattern":null,"preventionTips":["Run a config-schema lint in CI covering guardrail entries (name + litellm_params shape)","Start new guardrail entries by copying a known-good one so the name key is never dropped"],"tags":["openai-moderation","guardrails","configuration","litellm-proxy"],"backgroundTag":"missing-required-config","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}