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

ValueError from the enterprise custom SSO path: premium check passed, but user_custom_ui_sso_sign_in_handler (imported from litellm.proxy.proxy_server) is None. The proxy did not load a custom_ui_sso_sign_in_handler from general_settings, so there is nothing to delegate the sign-in to.

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 6c2dcb801b)

Solutions

Add custom_ui_sso_sign_in_handler: <module.path:function> under general_settings and restart the proxy
Verify the module imports cleanly: python -c 'import my_module; my_module.handler' inside the proxy's environment/container
Check startup logs for import errors around general_settings customization loading; fix PYTHONPATH or packaging so the handler resolves

Example fix

# before
general_settings:
  master_key: sk-123
  # custom_ui_sso_sign_in_handler missing

# after
general_settings:
  master_key: sk-123
  custom_ui_sso_sign_in_handler: enterprise_sso.custom_sign_in:handler

Defensive patterns

Strategy: validation

Validate before calling

# at startup, prove the handler loads in the proxy's env
import importlib
mod, fn = 'enterprise_sso.custom_sign_in', 'handler'
obj = getattr(importlib.import_module(mod), fn)
assert callable(obj)

Try / catch

try:
    httpx.get(f'{PROXY_URL}/ui/sso/sign-in')
except ValueError as e:
    if 'custom_ui_sso_sign_in_handler is not configured' in str(e):
        fix_config('add custom_ui_sso_sign_in_handler to general_settings')
    raise

Prevention

Smoke-test handler import inside the actual container image
Pin the handler module in the image (not a bind mount) to avoid path drift
Restart the proxy after every general_settings change

When it happens

Trigger: Hitting the custom UI SSO sign-in endpoint while general_settings lacks custom_ui_sso_sign_in_handler, or the configured module path failed to import at startup (silently leaving the module-level variable None).

Common situations: Typo in the handler's dotted module path in the config; the handler file not on PYTHONPATH inside the Docker image; config updated but proxy not restarted; the module raised during import and the error was only visible deep in startup logs.

Related errors

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