BerriAI/litellm · error · ValueError

Invalid mode: {custom_auth_settings['mode']}

Error message

Invalid mode: {custom_auth_settings['mode']}

What it means

ValueError from the enterprise custom-auth dispatcher: custom_auth_settings['mode'] was neither a recognized value. Supported modes include 'auto' (try custom auth, fall through to LiteLLM auth on non-ProxyException errors) and (per the branch above) another mode such as 'accept'; anything else hits the else-branch and raises 'Invalid mode: {mode}'.

Source

Thrown at enterprise/litellm_enterprise/proxy/auth/user_api_key_auth.py:35

    if custom_auth_settings is None:
        return await user_custom_auth(request, api_key)

    if custom_auth_settings["mode"] == "on":
        return await user_custom_auth(request, api_key)
    elif custom_auth_settings["mode"] == "off":
        return None
    elif custom_auth_settings["mode"] == "auto":
        try:
            return await user_custom_auth(request, api_key)
        except ProxyException as e:
            raise e
        except Exception as e:
            verbose_proxy_logger.debug(
                f"Error in custom auth, checking litellm auth: {e}"
            )
            return None
    else:
        raise ValueError(f"Invalid mode: {custom_auth_settings['mode']}")

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Set custom_auth_settings.mode to a documented supported value (e.g. 'auto') in the proxy config and restart
2. Validate the config YAML against current litellm docs/examples for custom_auth_settings before restart
3. Check startup logs: the dispatcher reads the setting lazily, so also confirm the parsed value with a config dump or debug logging

Example fix

# before
general_settings:
  custom_auth_settings:
    mode: autop   # invalid

# after
general_settings:
  custom_auth_settings:
    mode: auto

VALID_MODES = {'auto', 'accept'}
mode = cfg['general_settings']['custom_auth_settings']['mode']
assert mode in VALID_MODES, f'Invalid mode: {mode}'

def is_valid_auth_mode(cfg: dict) -> bool:
    cas = cfg.get('general_settings', {}).get('custom_auth_settings') or {}
    return cas.get('mode') in {'auto', 'accept'}

When it happens

Trigger: Configuring general_settings.custom_auth_settings with a typo'd or unsupported mode value, e.g. mode: 'Autop' or mode: 'passthrough', then making any request that goes through user_api_key_auth custom-auth dispatch.

Common situations: Upgrading litellm versions where the accepted mode vocabulary changed; YAML indentation putting mode under the wrong key so a dict/string is read as the mode; copying example config from outdated docs.

Related errors

• You must be a LiteLLM Enterprise user to use this feature. I
• custom_ui_sso_sign_in_handler is not configured. Please set
• Database not connected
• Setting tag based guardrail modes is only available in litel
• DB not connected. This endpoint needs a database; set DATABA

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/77116d967e04ecba. Report an issue: GitHub.