{"record":{"id":"a2387033b4550788","repo":"BerriAI/litellm","slug":"guardrail-configuration-error-init-error","errorCode":null,"errorMessage":"Guardrail configuration error: {init_error}","messagePattern":"Guardrail configuration error: (.+?)","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"litellm/proxy/guardrails/guardrail_endpoints.py","lineNumber":423,"sourceCode":"    try:\n        result = await GUARDRAIL_REGISTRY.add_guardrail_to_db(guardrail=request.guardrail, prisma_client=prisma_client)\n\n        guardrail_name: Final = result.get(\"guardrail_name\", \"Unknown\")\n        guardrail_id: Final = result.get(\"guardrail_id\", \"Unknown\")\n\n        try:\n            IN_MEMORY_GUARDRAIL_HANDLER.initialize_guardrail(guardrail=cast(Guardrail, result), source=\"db\")\n            verbose_proxy_logger.info(\n                \"Immediate sync: Successfully initialized guardrail '%s' (ID: %s)\", guardrail_name, guardrail_id\n            )\n        except (ValueError, TypeError) as init_error:\n            # Configuration error — roll back the DB write so the guardrail isn't orphaned\n            if prisma_client is not None:\n                try:\n                    await _delete_guardrail_row(prisma_client, where={\"guardrail_id\": guardrail_id})\n                except Exception as rollback_err:\n                    verbose_proxy_logger.warning(\"Rollback failed for guardrail '%s': %s\", guardrail_id, rollback_err)\n            raise HTTPException(\n                status_code=400,\n                detail=f\"Guardrail configuration error: {init_error}\",\n            )\n        except Exception as init_error:\n            verbose_proxy_logger.warning(\n                \"Immediate sync: Failed to initialize guardrail '%s' (ID: %s) in memory: %s\",\n                guardrail_name,\n                guardrail_id,\n                init_error,\n            )\n\n        return result\n    except Exception as e:\n        verbose_proxy_logger.exception(\"Error adding guardrail to db: %s\", e)\n        raise HTTPException(status_code=500, detail=str(e))\n\n\nclass UpdateGuardrailRequest(BaseModel):","sourceCodeStart":405,"sourceCodeEnd":441,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/guardrails/guardrail_endpoints.py#L405-L441","documentation":"POST /guardrails returns HTTP 400 'Guardrail configuration error: ...' when the guardrail row was written to the DB but IN_MEMORY_GUARDRAIL_HANDLER.initialize_guardrail() raised ValueError or TypeError — meaning the saved litellm_params are structurally invalid for instantiating the guardrail (unknown guardrail type, missing mode, bad field types). The handler rolls back the just-inserted row so no orphaned guardrail remains, then surfaces the underlying message.","triggerScenarios":"Creating a guardrail whose litellm_params.guardrail is an unsupported type name, omitting required params like mode or guardrailIdentifier/guardrailVersion for bedrock, or providing values with wrong types (e.g. default_on as string) so the runtime guardrail constructor throws ValueError/TypeError.","commonSituations":"Typos in the guardrail provider key ('bedrock' vs 'bedrock_guard'), configs copied from an older LiteLLM version whose param names changed, or a new custom guardrail class whose expected kwargs drifted from the API payload.","solutions":["Read the {init_error} suffix — it names the exact missing/invalid field; fix the litellm_params in the request body accordingly","Validate against the Guardrail pydantic schema and the target guardrail integration's required params (e.g. mode: pre_call, guardrailIdentifier, guardrailVersion for bedrock) before resubmitting","Check that litellm_params.guardrail matches a registered guardrail handler name in your LiteLLM version","The DB row was auto-rolled-back, so simply correct and re-POST — no manual cleanup needed unless rollback itself logged a warning"],"exampleFix":"# before\n{\"guardrail_name\": \"my-guard\", \"litellm_params\": {\"guardrail\": \"bedrok\", \"mode\": \"pre_call\"}}\n\n# after\n{\"guardrail_name\": \"my-guard\", \"litellm_params\": {\"guardrail\": \"bedrock\", \"mode\": \"pre_call\", \"guardrailIdentifier\": \"ff6ujrregl1q\", \"guardrailVersion\": \"DRAFT\"}}","handlingStrategy":"validation","validationCode":"REQUIRED_LITELLM_PARAMS = {\"guardrail\", \"mode\"}\n\ndef guardrail_params_look_valid(lp: dict) -> list[str]:\n    missing = [k for k in REQUIRED_LITELLM_PARAMS if not lp.get(k)]\n    if lp.get(\"guardrail\") == \"bedrock\":\n        missing += [k for k in (\"guardrailIdentifier\", \"guardrailVersion\") if not lp.get(k)]\n    return missing\n\nproblems = guardrail_params_look_valid(request_body[\"litellm_params\"])\nif problems:\n    raise ValueError(f\"Guardrail config missing: {problems}\")","typeGuard":"def is_known_guardrail_type(name: str) -> bool:\n    known = {\"bedrock\", \"aim\", \"presidio\", \"lakera\", \"aporia\", \"generic_guardrail_api\"}\n    return name in known","tryCatchPattern":"try:\n    r = requests.post(f\"{proxy}/guardrails\", json=guardrail, headers=h, timeout=30)\n    r.raise_for_status()\nexcept requests.HTTPError as e:\n    if e.response is not None and e.response.status_code == 400 and \"configuration error\" in e.response.text.lower():\n        # server rolled back the row; fix litellm_params from detail and re-submit\n        log.warning(\"Guardrail rejected: %s\", e.response.text)\n        raise ValueError(e.response.text) from e\n    raise","preventionTips":["Dry-run guardrail configs against the Guardrail pydantic model shipped with litellm before POSTing","Pin your LiteLLM version so guardrail param names don't drift under you","Read the {init_error} detail — it names the exact invalid field","Treat 400 'configuration error' as safe-to-retry-after-fix: the DB row was rolled back"],"tags":["litellm-proxy","guardrails","configuration","validation","rollback"],"backgroundTag":"config-validation-failed","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","schemaVersion":2},"datasetVersion":"2026-08-21T13:17:26.733Z"}