BerriAI/litellm · error · ValueError

Custom code guardrail requires a guardrail_name

Error message

Custom code guardrail requires a guardrail_name

What it means

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.

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/custom_code/__init__.py:39

    from litellm.types.guardrails import Guardrail, LitellmParams


def initialize_guardrail(litellm_params: "LitellmParams", guardrail: "Guardrail") -> CustomCodeGuardrail:
    """
    Initialize a custom code guardrail.

    Args:
        litellm_params: Configuration parameters including the custom code
        guardrail: The guardrail configuration dict

    Returns:
        CustomCodeGuardrail instance
    """
    import litellm

    guardrail_name: Final = guardrail.get("guardrail_name")
    if not guardrail_name:
        raise ValueError("Custom code guardrail requires a guardrail_name")

    # Get the custom code from litellm_params
    custom_code: Final = getattr(litellm_params, "custom_code", None)
    if not custom_code:
        raise ValueError("Custom code guardrail requires 'custom_code' in litellm_params")

    custom_code_guardrail: Final = CustomCodeGuardrail(
        guardrail_name=guardrail_name,
        custom_code=custom_code,
        event_hook=litellm_params.mode,
        default_on=litellm_params.default_on,
    )

    litellm.logging_callback_manager.add_litellm_callback(custom_code_guardrail)
    return custom_code_guardrail


guardrail_initializer_registry: Final = {

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Add a top-level, non-empty guardrail_name to the guardrails entry
2. Make sure the key sits at entry level (sibling of litellm_params), not inside it
3. Reload/restart the proxy and confirm the guardrail appears via the /guardrails endpoints

Example fix

# before
guardrails:
  - litellm_params:
      mode: guardrail_runs_before_llm_call
      custom_code: |
        def apply_guardrail(inputs, request_data, input_type):
            return allow()

# after
guardrails:
  - guardrail_name: my-custom-guardrail
    litellm_params:
      mode: guardrail_runs_before_llm_call
      custom_code: |
        def apply_guardrail(inputs, request_data, input_type):
            return allow()

import yaml

cfg = yaml.safe_load(open('config.yaml'))
for g in cfg.get('guardrails') or []:
    if not g.get('guardrail_name'):
        raise ValueError(f"guardrails entry missing top-level guardrail_name: {g}")

try:
    from litellm.proxy.guardrails.guardrail_hooks.custom_code import instantiate_custom_code_guardrail
    guardrail = instantiate_custom_code_guardrail(litellm_params=lp, guardrail=entry)
except ValueError as e:
    raise SystemExit(f'invalid guardrail config: {e}') from e

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Custom code guardrail requires 'custom_code' in litellm_para
• mcp_tools_config must be a list of dictionaries
• Invalid budget_reset_time {raw!r}; must be a quoted 24-hour
• Invalid budget_reset_time {raw!r}; expected a 24-hour 'HH:MM
• Guardrail configuration error: {init_error}

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