BerriAI/litellm · error · ValueError

custom_ui_sso_sign_in_handler is not configured. Please set…

Error message

custom_ui_sso_sign_in_handler is not configured. Please set it in general_settings.

What it means

Raised as a ValueError when premium checks pass but general_settings.custom_ui_sso_sign_in_handler is None - i.e. the request reached the custom UI SSO path without the handler being registered in the proxy config. The endpoint imports user_custom_ui_sso_sign_in_handler from litellm.proxy.proxy_server; if it was never set via config, it is None and this error fires before the trusted-proxy check runs.

Solutions

Add the handler under general_settings in the config used by the proxy: general_settings -> custom_ui_sso_sign_in_handler: <module.path:callable>
Confirm the proxy loads that exact config (check startup log line showing the config path, or LITELLM_CONFIG_URL_PATH)
Restart the proxy after the config change so proxy_server module state is refreshed
If you did not intend to use custom UI SSO, stop calling the custom SSO sign-in route
Check proxy logs for earlier import errors from the custom handler module - a failed import leaves the setting unset

Example fix

# before
# config.yaml
general_settings:
  master_key: sk-...
# -> ValueError: custom_ui_sso_sign_in_handler is not configured

# after
# config.yaml
general_settings:
  master_key: sk-...
  custom_ui_sso_sign_in_handler: custom_sso.my_handler

Defensive patterns

Strategy: validation

Validate before calling

# Startup assertion before serving traffic
from litellm.proxy.proxy_server import user_custom_ui_sso_sign_in_handler
assert user_custom_ui_sso_sign_in_handler is not None, (
    "custom_ui_sso_sign_in_handler missing in general_settings")

Try / catch

try:
    await handle_custom_sso(request)
except ValueError as e:
    if "not configured" in str(e):
        return JSONResponse({"error": "custom SSO not set up"}, status_code=501)
    raise

Prevention

Add a config lint step that requires the handler key when the custom SSO route is exposed
Watch proxy startup logs for import errors in custom handler modules
Version-control proxy config and diff it during rollouts

When it happens

Trigger: Hitting the custom UI SSO sign-in endpoint when the config yaml lacks general_settings.custom_ui_sso_sign_in_handler, or the handler module failed to import so the variable stayed None, or the config file deployed to this replica is an older version without the setting.

Common situations: Enabling an enterprise UI feature flag or route without adding the handler to proxy config; referencing the handler in a different config file than the one the proxy actually loads (LITELLM_CONFIG_URL_PATH mismatch); a config rollout that only updated some replicas.

Related errors

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

Appendix: source

Thrown at enterprise/litellm_enterprise/proxy/auth/custom_sso_handler.py:68

        """
        from fastapi_sso.sso.base import OpenID

        from litellm.integrations.custom_sso_handler import CustomSSOLoginHandler
        from litellm.proxy.proxy_server import (
            CommonProxyErrors,
            general_settings,
            premium_user,
            user_custom_ui_sso_sign_in_handler,
        )
        from litellm.proxy.auth.trusted_proxy_utils import (
            require_trusted_proxy_request,
        )

        if premium_user is not True:
            raise ValueError(CommonProxyErrors.not_premium_user.value)

        if user_custom_ui_sso_sign_in_handler is None:
            raise ValueError(
                "custom_ui_sso_sign_in_handler is not configured. Please set it in general_settings."
            )

        require_trusted_proxy_request(
            request=request,
            general_settings=general_settings,
            feature_name="Custom UI SSO",
        )

        custom_sso_login_handler = cast(
            CustomSSOLoginHandler, user_custom_ui_sso_sign_in_handler
        )
        openid_response: OpenID = (
            await custom_sso_login_handler.handle_custom_ui_sso_sign_in(
                request=request,
            )
        )

View on GitHub (pinned to 77b7c6c40c)