BerriAI/litellm · critical · ValueError

api_base is required for Generic Guardrail API. Set GENERIC_

Error message

api_base is required for Generic Guardrail API. Set GENERIC_GUARDRAIL_API_BASE environment variable or pass it in litellm_params

What it means

ValueError raised in GenericGuardrailAPI.__init__ when neither the api_base parameter nor the GENERIC_GUARDRAIL_API_BASE environment variable is set. The generic guardrail needs a full endpoint URL to POST to, and after this check it appends '/beta/litellm_basic_guardrail_api' to the base. It fails at guardrail construction time (config load / startup).

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/generic_guardrail_api/generic_guardrail_api.py:198

        fail_on_error: bool | None = True,
        extra_headers: list | None = None,
        streaming_end_of_stream_only: bool | None = None,
        streaming_sampling_rate: int | None = None,
        streaming_transform_mode: Literal["block_only", "incremental_diff"] | None = None,
        **kwargs,
    ):
        self.async_handler = get_async_httpx_client(llm_provider=httpxSpecialProvider.GuardrailCallback)
        self.headers = headers or {}
        self.extra_headers = extra_headers or []

        # If api_key is provided, add it as x-api-key header
        if api_key:
            self.headers["x-api-key"] = api_key

        base_url = api_base or os.environ.get("GENERIC_GUARDRAIL_API_BASE")

        if not base_url:
            raise ValueError(
                "api_base is required for Generic Guardrail API. "
                "Set GENERIC_GUARDRAIL_API_BASE environment variable or pass it in litellm_params"
            )

        # Append the endpoint path if not already present
        if not base_url.endswith("/beta/litellm_basic_guardrail_api"):
            base_url = base_url.rstrip("/")
            self.api_base = f"{base_url}/beta/litellm_basic_guardrail_api"
        else:
            self.api_base = base_url

        self.additional_provider_specific_params = additional_provider_specific_params or {}

        self.unreachable_fallback: Literal["fail_closed", "fail_open"] = unreachable_fallback

        self.fail_on_error: bool = True if fail_on_error is None else fail_on_error

        # Read by UnifiedLLMGuardrails.async_post_call_streaming_iterator_hook

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Set GENERIC_GUARDRAIL_API_BASE to your guardrail service root (e.g. https://guardrail.internal).
2. Or pass api_base directly in litellm_params for the guardrail.
3. If you pass a full URL, include /beta/litellm_basic_guardrail_api or it will be appended automatically.
4. Restart the proxy after fixing the environment.

Example fix

# before
litellm_params:
  guardrail: generic_guardrail_api
  api_key: os.environ/GUARDRAIL_API_KEY

# after
litellm_params:
  guardrail: generic_guardrail_api
  api_key: os.environ/GUARDRAIL_API_KEY
  api_base: os.environ/GENERIC_GUARDRAIL_API_BASE

import os, yaml

cfg = yaml.safe_load(open('config.yaml'))
for g in cfg.get('guardrails', []):
    p = g.get('litellm_params', {})
    if p.get('guardrail') == 'generic_guardrail_api' and not (p.get('api_base') or os.getenv('GENERIC_GUARDRAIL_API_BASE')):
        raise SystemExit(f"guardrail '{g.get('guardrail_name')}' has no api_base")

try:
    guardrail = GenericGuardrailAPI(litellm_params=cfg)
except ValueError as e:
    if 'GENERIC_GUARDRAIL_API_BASE' in str(e):
        logger.error('config incomplete: %s', e)
        raise
    raise

When it happens

Trigger: A guardrails-config entry with guardrail: generic_guardrail_api and no api_base in litellm_params while GENERIC_GUARDRAIL_API_BASE is unset; env var misspelled (GUARDRAIL vs GUARDRAILS); secret injection pipeline missing the variable.

Common situations: Bringing up a self-hosted/custom guardrail service for the first time; porting config between environments where the base URL was only in one env; the endpoint path suffix behavior surprising users who passed a full URL without the expected suffix.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• DynamoAI API key is required. Set DYNAMOAI_API_KEY environme
• EnkryptAI API key is required. Set ENKRYPTAI_API_KEY environ
• Gray Swan guardrail requires a guardrail_name
• llm_as_a_judge guardrail requires a guardrail_name
• llm_as_a_judge guardrail requires judge_model in litellm_par

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