BerriAI/litellm · error · ValueError

Oauth2 config mappings not found in general_settings

Error message

Oauth2 config mappings not found in general_settings

What it means

Config guard in the OAuth2-proxy auth hook: general_settings contains no oauth2 config mappings (oauth2_config), so header-to-identity mapping cannot run and the request cannot be authenticated via OAuth2 proxy headers.

Source

Thrown at litellm/proxy/auth/oauth2_proxy_hook.py:72

    ``ALLOWED_OAUTH2_PROXY_FIELDS`` (identity assertion only — see the
    constant's comment) may be mapped; any other mapping is rejected at
    request time so the misconfiguration surfaces loudly rather than as
    a silent privesc.
    """
    from litellm.proxy.proxy_server import general_settings

    verbose_proxy_logger.debug("Handling oauth2 proxy request")
    require_trusted_proxy_request(
        request=request,
        general_settings=general_settings,
        feature_name="OAuth2 proxy auth",
    )

    oauth2_config_mappings: Final[dict[str, str]] = general_settings.get("oauth2_config_mappings") or {}
    verbose_proxy_logger.debug("Oauth2 config mappings: %s", oauth2_config_mappings)

    if not oauth2_config_mappings:
        raise ValueError("Oauth2 config mappings not found in general_settings")

    disallowed: Final = sorted(set(oauth2_config_mappings.keys()) - ALLOWED_OAUTH2_PROXY_FIELDS)
    if disallowed:
        raise ValueError(
            "Oauth2 proxy auth refuses to map non-identity UserAPIKeyAuth "
            f"fields from request headers: {disallowed}. Only identity "
            f"fields are accepted ({sorted(ALLOWED_OAUTH2_PROXY_FIELDS)}); "
            "anything else (privileges, budgets, rate limits, metadata) "
            "would let a caller forge enforcement parameters by spoofing "
            "the matching header. If you need a trusted upstream to "
            "assert anything beyond identity, use JWT auth "
            "(signature-validated) instead of header-trust."
        )

    auth_data: Final[Mapping[str, str | list[str]]] = {
        key: [model.strip() for model in value.split(",")] if key == "models" else value
        for key, header in oauth2_config_mappings.items()
        if (value := request.headers.get(header))

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Add the oauth2 config mappings under general_settings in your proxy config.yaml.

Example fix

general_settings:
  oauth2_config_mappings:
    user_id_header: X-User-Id

When it happens

Trigger: Thrown at litellm/proxy/auth/oauth2_proxy_hook.py:72 when the library encounters an invalid state.

Common situations: The OAuth2 proxy hook is enabled but no config mappings exist in general_settings.

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