BerriAI/litellm · critical · ValueError

Block Code Execution guardrail requires a guardrail_name

Error message

Block Code Execution guardrail requires a guardrail_name

What it means

litellm's proxy raises this ValueError at startup/config-load time when a guardrail entry of type block_code_execution has no guardrail_name key. Every guardrail in the config's guardrails list must carry a unique guardrail_name because it is the identifier used by mode/enabled hooks, request-level guardrail selection (guardrails=[...] on a /chat/completions call), and logging. Without it the guardrail cannot be registered, so initialization aborts immediately.

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/block_code_execution/__init__.py:44

    value: Final = getattr(litellm_params, key, default)
    if value is not None:
        return value
    raw: Final = guardrail.get("litellm_params")
    if isinstance(raw, dict) and key in raw:
        return raw[key]
    return default


def initialize_guardrail(
    litellm_params: "LitellmParams",
    guardrail: "Guardrail",
) -> BlockCodeExecutionGuardrail:
    """Initialize the Block Code Execution guardrail from config."""
    import litellm

    guardrail_name: Final = guardrail.get("guardrail_name")
    if not guardrail_name:
        raise ValueError("Block Code Execution guardrail requires a guardrail_name")

    blocked_languages: Final[list[str] | None] = cast(
        list[str] | None,
        _get_param(litellm_params, guardrail, "blocked_languages"),
    )
    action: Final = cast(
        Literal["block", "mask"],
        _get_param(litellm_params, guardrail, "action", "block"),
    )
    confidence_threshold: Final = float(
        cast(
            int | float | str,
            _get_param(litellm_params, guardrail, "confidence_threshold", 0.5),
        )
    )
    detect_execution_intent: Final = bool(_get_param(litellm_params, guardrail, "detect_execution_intent", True))
    mode: Final = _get_param(litellm_params, guardrail, "mode")
    event_hook: Final = cast(

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Add a unique top-level guardrail_name to the guardrail entry (sibling of litellm_params, not inside it).
2. Confirm the YAML structure: guardrails is a list; each item has guardrail_name plus litellm_params; run the config through a YAML linter or litellm's config validator.
3. If you hot-reload configs, restart the proxy after fixing so initialize_guardrail re-runs.

Example fix

# before
guardrails:
  - litellm_params:
      guardrail: block_code_execution
      blocked_languages: [python, bash]

# after
guardrails:
  - guardrail_name: block-code-execution-pre-call
    litellm_params:
      guardrail: block_code_execution
      blocked_languages: [python, bash]

import yaml
cfg = yaml.safe_load(open("config.yaml"))
for g in cfg.get("guardrails", []):
    if g.get("litellm_params", {}).get("guardrail") == "block_code_execution":
        assert isinstance(g.get("guardrail_name"), str) and g["guardrail_name"].strip(), (
            f"block_code_execution entry missing guardrail_name: {g}")
        assert g["guardrail_name"] not in names; names.add(g["guardrail_name"])

from typing import Any
def is_valid_guardrail_entry(entry: Any) -> bool:
    return (
        isinstance(entry, dict)
        and isinstance(entry.get("guardrail_name"), str)
        and bool(entry["guardrail_name"].strip())
        and isinstance(entry.get("litellm_params"), dict)
    )

When it happens

Trigger: Adding a guardrails: [{litellm_params: {guardrail: block_code_execution, ...}}] entry to the proxy config without a top-level guardrail_name field, then starting litellm proxy or hot-reloading the config. initialize_guardrail() reads guardrail.get('guardrail_name'), gets None, and raises.

Common situations: Copy-pasting a guardrail config block from docs and dropping the name field; refactoring config where guardrail_name was accidentally nested under litellm_params (it must be a sibling, at the entry top level); YAML indentation mistakes that move guardrail_name into the wrong mapping.

Related errors

• Couldn't get Cato Networks api key, either set the `CATO_API
• Cisco AI Defense API key is required. Set `CISCO_AI_DEFENSE_
• Compresr guardrail requires an API key. Set `api_key` in the
• CrowdStrike AIDR guardrail name is required
• Bedrock guardrail failed: {e}

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