{"record":{"id":"cc160983188c5bab","repo":"BerriAI/litellm","slug":"custom-code-guardrail-requires-a-guardrail-name","errorCode":null,"errorMessage":"Custom code guardrail requires a guardrail_name","messagePattern":"Custom code guardrail requires a guardrail_name","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/proxy/guardrails/guardrail_hooks/custom_code/__init__.py","lineNumber":39,"sourceCode":"    from litellm.types.guardrails import Guardrail, LitellmParams\n\n\ndef initialize_guardrail(litellm_params: \"LitellmParams\", guardrail: \"Guardrail\") -> CustomCodeGuardrail:\n    \"\"\"\n    Initialize a custom code guardrail.\n\n    Args:\n        litellm_params: Configuration parameters including the custom code\n        guardrail: The guardrail configuration dict\n\n    Returns:\n        CustomCodeGuardrail instance\n    \"\"\"\n    import litellm\n\n    guardrail_name: Final = guardrail.get(\"guardrail_name\")\n    if not guardrail_name:\n        raise ValueError(\"Custom code guardrail requires a guardrail_name\")\n\n    # Get the custom code from litellm_params\n    custom_code: Final = getattr(litellm_params, \"custom_code\", None)\n    if not custom_code:\n        raise ValueError(\"Custom code guardrail requires 'custom_code' in litellm_params\")\n\n    custom_code_guardrail: Final = CustomCodeGuardrail(\n        guardrail_name=guardrail_name,\n        custom_code=custom_code,\n        event_hook=litellm_params.mode,\n        default_on=litellm_params.default_on,\n    )\n\n    litellm.logging_callback_manager.add_litellm_callback(custom_code_guardrail)\n    return custom_code_guardrail\n\n\nguardrail_initializer_registry: Final = {","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/guardrails/guardrail_hooks/custom_code/__init__.py#L21-L57","documentation":"ValueError raised by the custom-code guardrail factory (instantiate path in guardrail_hooks/custom_code/__init__.py) when the guardrails config entry has no guardrail_name. LiteLLM requires every guardrail to be named — the name is used for callback registration, logging, and the /guardrails management API — so an unnamed entry is rejected at guardrail instantiation.","triggerScenarios":"A config.yaml guardrails list entry that includes litellm_params.custom_code (or a mode that routes to the custom-code factory) but omits the top-level guardrail_name field, or sets it to an empty value.","commonSituations":"Hand-written YAML where the name key was forgotten or accidentally nested inside litellm_params; copy-paste from an example that omitted it; renaming cleanup removed the key.","solutions":["Add a top-level, non-empty guardrail_name to the guardrails entry","Make sure the key sits at entry level (sibling of litellm_params), not inside it","Reload/restart the proxy and confirm the guardrail appears via the /guardrails endpoints"],"exampleFix":"# before\nguardrails:\n  - litellm_params:\n      mode: guardrail_runs_before_llm_call\n      custom_code: |\n        def apply_guardrail(inputs, request_data, input_type):\n            return allow()\n\n# after\nguardrails:\n  - guardrail_name: my-custom-guardrail\n    litellm_params:\n      mode: guardrail_runs_before_llm_call\n      custom_code: |\n        def apply_guardrail(inputs, request_data, input_type):\n            return allow()","handlingStrategy":"validation","validationCode":"import yaml\n\ncfg = yaml.safe_load(open('config.yaml'))\nfor g in cfg.get('guardrails') or []:\n    if not g.get('guardrail_name'):\n        raise ValueError(f\"guardrails entry missing top-level guardrail_name: {g}\")","typeGuard":null,"tryCatchPattern":"try:\n    from litellm.proxy.guardrails.guardrail_hooks.custom_code import instantiate_custom_code_guardrail\n    guardrail = instantiate_custom_code_guardrail(litellm_params=lp, guardrail=entry)\nexcept ValueError as e:\n    raise SystemExit(f'invalid guardrail config: {e}') from e","preventionTips":["Schema-check guardrails entries (guardrail_name present, non-empty, at entry level) in CI","After deploy, assert the guardrail is listed via the /guardrails management endpoint"],"tags":["guardrails","custom-code","config","yaml","validation","litellm-proxy"],"backgroundTag":"guardrail-misconfigured","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","schemaVersion":2},"datasetVersion":"2026-08-21T13:17:26.733Z"}