BerriAI/litellm · error · ValueError

{feature_name} requires general_settings.{setting_name} befo

Error message

{feature_name} requires general_settings.{setting_name} before trusting identity headers from an upstream proxy.

What it means

LiteLLM fails closed when a feature derives identity from proxy-supplied headers: require_trusted_proxy_request (trusted_proxy_utils.py) requires trusted reverse-proxy CIDR ranges configured under general_settings.trusted_proxy_ranges. If the setting is missing or empty, this ValueError is raised (message interpolates the feature name, e.g. 'OAuth2 proxy auth') instead of silently trusting spoofable X-Forwarded-* identity headers.

Source

Thrown at litellm/proxy/auth/trusted_proxy_utils.py:68

    request: Request,
    general_settings: dict[str, Any] | None = None,
    feature_name: str,
    setting_name: str = TRUSTED_PROXY_RANGES_KEY,
) -> None:
    """
    Fail closed unless the direct TCP peer is one of the configured
    trusted reverse proxies.

    Header-based auth paths must validate the direct peer, not
    X-Forwarded-For, because the direct peer is the actor supplying the
    identity headers.
    """
    if general_settings is None:
        general_settings = _get_proxy_general_settings()

    trusted_networks: Final = parse_trusted_proxy_ranges(general_settings.get(setting_name), setting_name=setting_name)
    if not trusted_networks:
        raise ValueError(
            f"{feature_name} requires general_settings.{setting_name} before "
            "trusting identity headers from an upstream proxy."
        )

    direct_client_ip: Final = _get_direct_client_ip(request)
    if not ip_in_networks(direct_client_ip, trusted_networks):
        verbose_proxy_logger.warning(
            "%s rejected identity headers from untrusted direct client IP %r",
            feature_name,
            direct_client_ip,
        )
        raise ValueError(
            f"{feature_name} only accepts identity headers from configured "
            f"trusted proxy ranges. Direct client IP {direct_client_ip!r} "
            "is not trusted."
        )

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Add your proxy's real CIDR(s) under general_settings.trusted_proxy_ranges in config.yaml and restart
2. Make sure trusted_proxy_ranges sits in general_settings, not litellm_settings
3. Configure the LB/ingress node or pod CIDR - the ranges must cover the proxy's egress IPs, not end-user IPs

Example fix

# before (config.yaml)
general_settings:
  enable_oauth2_proxy_auth: true        # ValueError: requires general_settings.trusted_proxy_ranges

# after
general_settings:
  enable_oauth2_proxy_auth: true
  trusted_proxy_ranges: ['10.0.0.0/8', '192.168.1.0/24']   # your reverse proxy / ingress CIDRs

# Python: lint the config before deploy - header-identity features need trusted_proxy_ranges
import yaml
cfg = yaml.safe_load(open('config.yaml'))
gs = cfg.get('general_settings', {})
HEADER_IDENTITY_FEATURES = [('enable_oauth2_proxy_auth', 'OAuth2 proxy auth')]
for setting, feature in HEADER_IDENTITY_FEATURES:
    if gs.get(setting) and not gs.get('trusted_proxy_ranges'):
        raise ValueError(f'{feature} requires general_settings.trusted_proxy_ranges')

try:
    await handle_oauth2_proxy_request(request)
except ValueError as e:
    if 'requires general_settings' in str(e):
        log.error('proxy misconfigured: %s - add trusted_proxy_ranges before trusting identity headers', e)
        return JSONResponse({'error': 'proxy misconfigured'}, status_code=503)
    raise

When it happens

Trigger: Enabling enable_oauth2_proxy_auth (or another header-identity feature that routes through require_trusted_proxy_request) without setting general_settings.trusted_proxy_ranges in the proxy config.

Common situations: New deployments behind a reverse proxy copy the auth settings but omit the CIDR list; the key is accidentally placed under litellm_settings instead of general_settings; staging (direct access) works while prod (behind an LB) fails.

Related errors

• {feature_name} only accepts identity headers from configured
• Encryption migration requires general_settings.encryption_al
• Invalid identifier {identifier!r}: contains disallowed chara
• Invalid identifier {identifier!r}: path traversal detected
• Invalid file path {file_path!r}: path traversal detected

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