{"record":{"id":"120fd2f3528d7700","repo":"BerriAI/litellm","slug":"feature-name-requires-general-settings-setting","errorCode":null,"errorMessage":"{feature_name} requires general_settings.{setting_name} before trusting identity headers from an upstream proxy.","messagePattern":"(.+?) requires general_settings\\.(.+?) before trusting identity headers from an upstream proxy\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/proxy/auth/trusted_proxy_utils.py","lineNumber":68,"sourceCode":"    request: Request,\n    general_settings: dict[str, Any] | None = None,\n    feature_name: str,\n    setting_name: str = TRUSTED_PROXY_RANGES_KEY,\n) -> None:\n    \"\"\"\n    Fail closed unless the direct TCP peer is one of the configured\n    trusted reverse proxies.\n\n    Header-based auth paths must validate the direct peer, not\n    X-Forwarded-For, because the direct peer is the actor supplying the\n    identity headers.\n    \"\"\"\n    if general_settings is None:\n        general_settings = _get_proxy_general_settings()\n\n    trusted_networks: Final = parse_trusted_proxy_ranges(general_settings.get(setting_name), setting_name=setting_name)\n    if not trusted_networks:\n        raise ValueError(\n            f\"{feature_name} requires general_settings.{setting_name} before \"\n            \"trusting identity headers from an upstream proxy.\"\n        )\n\n    direct_client_ip: Final = _get_direct_client_ip(request)\n    if not ip_in_networks(direct_client_ip, trusted_networks):\n        verbose_proxy_logger.warning(\n            \"%s rejected identity headers from untrusted direct client IP %r\",\n            feature_name,\n            direct_client_ip,\n        )\n        raise ValueError(\n            f\"{feature_name} only accepts identity headers from configured \"\n            f\"trusted proxy ranges. Direct client IP {direct_client_ip!r} \"\n            \"is not trusted.\"\n        )\n","sourceCodeStart":50,"sourceCodeEnd":85,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/auth/trusted_proxy_utils.py#L50-L85","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add your proxy's real CIDR(s) under general_settings.trusted_proxy_ranges in config.yaml and restart","Make sure trusted_proxy_ranges sits in general_settings, not litellm_settings","Configure the LB/ingress node or pod CIDR - the ranges must cover the proxy's egress IPs, not end-user IPs"],"exampleFix":"# before (config.yaml)\ngeneral_settings:\n  enable_oauth2_proxy_auth: true        # ValueError: requires general_settings.trusted_proxy_ranges\n\n# after\ngeneral_settings:\n  enable_oauth2_proxy_auth: true\n  trusted_proxy_ranges: ['10.0.0.0/8', '192.168.1.0/24']   # your reverse proxy / ingress CIDRs","handlingStrategy":"validation","validationCode":"# Python: lint the config before deploy - header-identity features need trusted_proxy_ranges\nimport yaml\ncfg = yaml.safe_load(open('config.yaml'))\ngs = cfg.get('general_settings', {})\nHEADER_IDENTITY_FEATURES = [('enable_oauth2_proxy_auth', 'OAuth2 proxy auth')]\nfor setting, feature in HEADER_IDENTITY_FEATURES:\n    if gs.get(setting) and not gs.get('trusted_proxy_ranges'):\n        raise ValueError(f'{feature} requires general_settings.trusted_proxy_ranges')","typeGuard":null,"tryCatchPattern":"try:\n    await handle_oauth2_proxy_request(request)\nexcept ValueError as e:\n    if 'requires general_settings' in str(e):\n        log.error('proxy misconfigured: %s - add trusted_proxy_ranges before trusting identity headers', e)\n        return JSONResponse({'error': 'proxy misconfigured'}, status_code=503)\n    raise","preventionTips":["Add trusted_proxy_ranges to the same config template that enables any proxy-header auth feature","Put the setting under general_settings, not litellm_settings","Run a startup config lint (like the snippet) in CI so omissions fail before deploy"],"tags":["config","trusted-proxy","oauth2-proxy","x-forwarded-for","security"],"backgroundTag":"missing-config-setting","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}