BerriAI/litellm · critical · ValueError

Gray Swan guardrail requires a guardrail_name

Error message

Gray Swan guardrail requires a guardrail_name

What it means

ValueError raised in the grayswan initialize_guardrail factory when the guardrail config entry has no guardrail_name field. Every LiteLLM guardrail is keyed by guardrail_name (used for mode matching, logging, and the applied-guardrails header), so the GraySwan constructor cannot proceed without it. Fails during config loading at startup.

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/grayswan/__init__.py:22

from litellm.types.guardrails import SupportedGuardrailIntegrations

from .grayswan import (
    GraySwanGuardrail,
    GraySwanGuardrailAPIError,
    GraySwanGuardrailMissingSecrets,
)

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


def initialize_guardrail(litellm_params: "LitellmParams", guardrail: "Guardrail") -> GraySwanGuardrail:
    import litellm

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

    optional_params: Final = getattr(litellm_params, "optional_params", None)

    grayswan_guardrail: Final = GraySwanGuardrail(
        guardrail_name=guardrail_name,
        api_key=litellm_params.api_key,
        api_base=litellm_params.api_base,
        on_flagged_action=_get_config_value(litellm_params, optional_params, "on_flagged_action"),
        violation_threshold=_get_config_value(litellm_params, optional_params, "violation_threshold"),
        reasoning_mode=_get_config_value(litellm_params, optional_params, "reasoning_mode"),
        categories=_get_config_value(litellm_params, optional_params, "categories"),
        policy_id=_get_config_value(litellm_params, optional_params, "policy_id"),
        streaming_end_of_stream_only=_get_config_value(litellm_params, optional_params, "streaming_end_of_stream_only")
        or False,
        streaming_sampling_rate=_get_config_value(litellm_params, optional_params, "streaming_sampling_rate") or 5,
        fail_open=_get_config_value(litellm_params, optional_params, "fail_open"),
        guardrail_timeout=_get_config_value(litellm_params, optional_params, "guardrail_timeout"),
        event_hook=litellm_params.mode,

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Add a top-level guardrail_name to the entry (sibling of litellm_params, not nested inside it).
2. Validate the YAML structure against another working guardrail entry.
3. Reload/restart the proxy after fixing the config.

Example fix

# before
guardrails:
  - litellm_params:
      guardrail: grayswan
      api_key: os.environ/GRAYSWAN_API_KEY

# after
guardrails:
  - guardrail_name: grayswan-primary
    litellm_params:
      guardrail: grayswan
      api_key: os.environ/GRAYSWAN_API_KEY

import yaml

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

When it happens

Trigger: A guardrails-config entry for grayswan with litellm_params but a missing or empty guardrail_name key; YAML indentation putting guardrail_name under litellm_params instead of the entry root.

Common situations: Hand-written YAML where the name key was forgotten or misspelled (name:, guardrail:); config generated by a template that omits the field; copy-paste from a docs example that used a placeholder.

Related errors

• DynamoAI API key is required. Set DYNAMOAI_API_KEY environme
• EnkryptAI API key is required. Set ENKRYPTAI_API_KEY environ
• api_base is required for Generic Guardrail API. Set GENERIC_
• Gray Swan API key missing. Set `GRAYSWAN_API_KEY` or pass `a
• llm_as_a_judge guardrail requires a guardrail_name

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