{"record":{"id":"a9db4896200f5990","repo":"BerriAI/litellm","slug":"content-filter-guardrail-name-is-required","errorCode":null,"errorMessage":"Content Filter: guardrail_name is required","messagePattern":"Content Filter: guardrail_name is required","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/__init__.py","lineNumber":32,"sourceCode":"def initialize_guardrail(\n    litellm_params: \"LitellmParams\",\n    guardrail: \"Guardrail\",\n    llm_router: Optional[\"Router\"] = None,\n):\n    \"\"\"\n    Initialize the Content Filter Guardrail.\n\n    Args:\n        litellm_params: Guardrail configuration parameters\n        guardrail: Guardrail metadata\n\n    Returns:\n        Initialized ContentFilterGuardrail instance\n    \"\"\"\n    guardrail_name: Final = guardrail.get(\"guardrail_name\")\n\n    if not guardrail_name:\n        raise ValueError(\"Content Filter: guardrail_name is required\")\n\n    content_filter_guardrail: Final = ContentFilterGuardrail(\n        guardrail_name=guardrail_name,\n        guardrail_id=guardrail.get(\"guardrail_id\"),\n        policy_template=guardrail.get(\"policy_template\"),\n        patterns=litellm_params.patterns,\n        blocked_words=litellm_params.blocked_words,\n        blocked_words_file=litellm_params.blocked_words_file,\n        event_hook=litellm_params.mode,\n        default_on=litellm_params.default_on or False,\n        categories=getattr(litellm_params, \"categories\", None),\n        severity_threshold=getattr(litellm_params, \"severity_threshold\", \"medium\"),\n        llm_router=llm_router,\n        image_model=getattr(litellm_params, \"image_model\", None),\n        competitor_intent_config=getattr(litellm_params, \"competitor_intent_config\", None),\n        end_session_after_n_fails=getattr(litellm_params, \"end_session_after_n_fails\", None),\n        on_violation=getattr(litellm_params, \"on_violation\", None),\n        realtime_violation_message=getattr(litellm_params, \"realtime_violation_message\", None),","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/__init__.py#L14-L50","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add guardrail_name: <unique-name> at the guardrail entry level (sibling of litellm_params, not inside it).","Check YAML indentation — guardrail_name must sit next to litellm_params for the same list item.","Lint the config before deploy: assert every entry under guardrails has a non-empty guardrail_name.","If registering programmatically, include 'guardrail_name' in the guardrail metadata dict passed to the factory."],"exampleFix":"# before\nlitellm_settings:\n  guardrails:\n    - litellm_params:\n        guardrail: litellm_content_filter\n        mode: pre_call\n\n# after\nlitellm_settings:\n  guardrails:\n    - guardrail_name: my-content-filter\n      litellm_params:\n        guardrail: litellm_content_filter\n        mode: pre_call","handlingStrategy":"validation","validationCode":"# Config lint: every guardrail entry needs a non-empty guardrail_name\nimport yaml\n\ndef lint_guardrail_names(path: str = \"config.yaml\") -> list[str]:\n    cfg = yaml.safe_load(open(path))\n    problems = []\n    for g in cfg.get(\"litellm_settings\", {}).get(\"guardrails\", []):\n        if not g.get(\"guardrail_name\"):\n            problems.append(f\"guardrail entry missing guardrail_name: {g}\")\n    return problems\n\n# assert not lint_guardrail_names() in CI","typeGuard":"from typing import Any\n\ndef is_valid_guardrail_entry(entry: Any) -> bool:\n    \"\"\"Narrow a parsed YAML guardrail entry to a well-formed one.\"\"\"\n    return (\n        isinstance(entry, dict)\n        and isinstance(entry.get(\"guardrail_name\"), str)\n        and bool(entry[\"guardrail_name\"].strip())\n        and isinstance(entry.get(\"litellm_params\"), dict)\n    )","tryCatchPattern":null,"preventionTips":["Keep guardrail_name at entry level (sibling of litellm_params) — the most common indentation mistake.","Use a YAML schema (or the lint above) in CI to catch missing fields before deploy.","Give guardrails stable, unique names; they key logs, metrics, and per-guardrail routing."],"tags":["configuration","validation","content-filter","guardrails"],"backgroundTag":"missing-config-field","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}