{"record":{"id":"c572252be30a3343","repo":"BerriAI/litellm","slug":"gray-swan-guardrail-requires-a-guardrail-name","errorCode":null,"errorMessage":"Gray Swan guardrail requires a guardrail_name","messagePattern":"Gray Swan guardrail requires a guardrail_name","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"litellm/proxy/guardrails/guardrail_hooks/grayswan/__init__.py","lineNumber":22,"sourceCode":"\nfrom litellm.types.guardrails import SupportedGuardrailIntegrations\n\nfrom .grayswan import (\n    GraySwanGuardrail,\n    GraySwanGuardrailAPIError,\n    GraySwanGuardrailMissingSecrets,\n)\n\nif TYPE_CHECKING:\n    from litellm.types.guardrails import Guardrail, LitellmParams\n\n\ndef initialize_guardrail(litellm_params: \"LitellmParams\", guardrail: \"Guardrail\") -> GraySwanGuardrail:\n    import litellm\n\n    guardrail_name: Final = guardrail.get(\"guardrail_name\")\n    if not guardrail_name:\n        raise ValueError(\"Gray Swan guardrail requires a guardrail_name\")\n\n    optional_params: Final = getattr(litellm_params, \"optional_params\", None)\n\n    grayswan_guardrail: Final = GraySwanGuardrail(\n        guardrail_name=guardrail_name,\n        api_key=litellm_params.api_key,\n        api_base=litellm_params.api_base,\n        on_flagged_action=_get_config_value(litellm_params, optional_params, \"on_flagged_action\"),\n        violation_threshold=_get_config_value(litellm_params, optional_params, \"violation_threshold\"),\n        reasoning_mode=_get_config_value(litellm_params, optional_params, \"reasoning_mode\"),\n        categories=_get_config_value(litellm_params, optional_params, \"categories\"),\n        policy_id=_get_config_value(litellm_params, optional_params, \"policy_id\"),\n        streaming_end_of_stream_only=_get_config_value(litellm_params, optional_params, \"streaming_end_of_stream_only\")\n        or False,\n        streaming_sampling_rate=_get_config_value(litellm_params, optional_params, \"streaming_sampling_rate\") or 5,\n        fail_open=_get_config_value(litellm_params, optional_params, \"fail_open\"),\n        guardrail_timeout=_get_config_value(litellm_params, optional_params, \"guardrail_timeout\"),\n        event_hook=litellm_params.mode,","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/guardrails/guardrail_hooks/grayswan/__init__.py#L4-L40","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add a top-level guardrail_name to the entry (sibling of litellm_params, not nested inside it).","Validate the YAML structure against another working guardrail entry.","Reload/restart the proxy after fixing the config."],"exampleFix":"# before\nguardrails:\n  - litellm_params:\n      guardrail: grayswan\n      api_key: os.environ/GRAYSWAN_API_KEY\n\n# after\nguardrails:\n  - guardrail_name: grayswan-primary\n    litellm_params:\n      guardrail: grayswan\n      api_key: os.environ/GRAYSWAN_API_KEY","handlingStrategy":"validation","validationCode":"import yaml\n\ncfg = yaml.safe_load(open('config.yaml'))\nfor g in cfg.get('guardrails', []):\n    if not g.get('guardrail_name'):\n        raise SystemExit(f\"guardrail entry missing top-level 'guardrail_name': {g}\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep guardrail_name a sibling of litellm_params, never nested inside it.","Validate guardrail config structure in CI with a YAML schema or lint step.","Copy a known-good guardrail entry as the template for new ones."],"tags":["grayswan","guardrail","config","yaml","startup"],"backgroundTag":"missing-required-config-field","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}