BerriAI/litellm · error · ValueError

MCP Security: guardrail_name is required

Error message

MCP Security: guardrail_name is required

What it means

initialize_guardrail() for the MCP security guardrail requires guardrail_name on the guardrail entry and raises ValueError without it. As with other guardrail init errors, it fires at proxy startup or config reload when the mcp_security entry is malformed.

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/mcp_security/__init__.py:21

import litellm
from litellm.proxy.guardrails.guardrail_hooks.mcp_security.mcp_security_guardrail import (
    MCPSecurityGuardrail,
)
from litellm.types.guardrails import SupportedGuardrailIntegrations

if TYPE_CHECKING:
    from litellm import Router
    from litellm.types.guardrails import Guardrail, LitellmParams


def initialize_guardrail(
    litellm_params: "LitellmParams",
    guardrail: "Guardrail",
    llm_router: Optional["Router"] = None,
):
    guardrail_name: Final = guardrail.get("guardrail_name")
    if not guardrail_name:
        raise ValueError("MCP Security: guardrail_name is required")

    on_violation: Final[Literal["block", "alert"]] = cast(
        Literal["block", "alert"],
        getattr(litellm_params, "on_violation", "block"),
    )

    mcp_security_guardrail: Final = MCPSecurityGuardrail(
        guardrail_name=guardrail_name,
        event_hook=litellm_params.mode,
        default_on=litellm_params.default_on or False,
        on_violation=on_violation,
    )

    litellm.logging_callback_manager.add_litellm_callback(mcp_security_guardrail)
    return mcp_security_guardrail


guardrail_initializer_registry: Final = {

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Add guardrail_name: <unique-name> to the mcp_security guardrail entry
2. Add a config lint step that asserts every guardrails entry has a non-empty guardrail_name

Example fix

# before
 guardrails:
   - guardrail: mcp_security
     litellm_params:
       mode: pre_call

# after
 guardrails:
   - guardrail: mcp_security
     guardrail_name: mcp-security
     litellm_params:
       mode: pre_call

for g in config.get("guardrails", []):  
    assert g.get("guardrail_name"), f"guardrail {g.get('guardrail')!r} missing guardrail_name"

def has_guardrail_name(entry: object) -> bool:  
    return isinstance(entry, dict) and isinstance(entry.get("guardrail_name"), str) and bool(entry["guardrail_name"].strip())

When it happens

Trigger: A guardrails config entry enabling the mcp_security guardrail without a guardrail_name key.

Common situations: Hand-assembled guardrail YAML missing the name line; config templating that drops empty-name entries; entries written by mirroring other guardrails' minimal forms.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• MCPJWTSigner guardrail requires a guardrail_name
• MCPJWTSigner: ttl_seconds must be > 0, got {resolved_ttl}
• mcp_tools_config is required, please set `mcp_tools` in your
• DynamoAI API key is required. Set DYNAMOAI_API_KEY environme
• EnkryptAI API key is required. Set ENKRYPTAI_API_KEY environ

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