{"record":{"id":"77116d967e04ecba","repo":"BerriAI/litellm","slug":"invalid-mode-custom-auth-settings-mode","errorCode":null,"errorMessage":"Invalid mode: {custom_auth_settings['mode']}","messagePattern":"Invalid mode: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"enterprise/litellm_enterprise/proxy/auth/user_api_key_auth.py","lineNumber":35,"sourceCode":"    if custom_auth_settings is None:\n        return await user_custom_auth(request, api_key)\n\n    if custom_auth_settings[\"mode\"] == \"on\":\n        return await user_custom_auth(request, api_key)\n    elif custom_auth_settings[\"mode\"] == \"off\":\n        return None\n    elif custom_auth_settings[\"mode\"] == \"auto\":\n        try:\n            return await user_custom_auth(request, api_key)\n        except ProxyException as e:\n            raise e\n        except Exception as e:\n            verbose_proxy_logger.debug(\n                f\"Error in custom auth, checking litellm auth: {e}\"\n            )\n            return None\n    else:\n        raise ValueError(f\"Invalid mode: {custom_auth_settings['mode']}\")\n","sourceCodeStart":17,"sourceCodeEnd":36,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/enterprise/litellm_enterprise/proxy/auth/user_api_key_auth.py#L17-L36","documentation":"Raised as a ValueError by enterprise_custom_auth when custom_auth_settings is non-null but its 'mode' key is not one of the three supported values ('on', 'off', 'auto'). The mode controls how the custom auth callable interacts with LiteLLM's built-in auth: 'on' always runs it, 'off' skips it, 'auto' falls back to LiteLLM auth on non-ProxyException errors. Any other string aborts auth setup with this error.","triggerScenarios":"Defining custom_auth_settings in the enterprise proxy config with a typo'd or unsupported mode value such as 'true', 'enabled', 'always', or 'ON' (matching is case-sensitive lowercase); passing a mode key the enterprise build added in a later version than the one deployed.","commonSituations":"Hand-written config yaml with custom_auth_settings: {mode: enabled}; upgrading/downgrading the enterprise package where the accepted mode vocabulary changed; config generated by templating that injects a boolean instead of a string.","solutions":["Set the mode to exactly 'on', 'off', or 'auto' (lowercase) in custom_auth_settings","Remove custom_auth_settings entirely if you want the default behavior (handler always called)","Validate the config against the documented schema before deploy (litellm proxy config check)"],"exampleFix":"# before\ncustom_auth_settings:\n  mode: enabled   # -> ValueError: Invalid mode: enabled\n# after\ncustom_auth_settings:\n  mode: auto      # fall back to LiteLLM auth on handler errors","handlingStrategy":"validation","validationCode":"VALID_MODES = {\"on\", \"off\", \"auto\"}\nassert custom_auth_settings is None or custom_auth_settings[\"mode\"] in VALID_MODES, (\n    f\"custom_auth_settings.mode must be one of {sorted(VALID_MODES)}\")","typeGuard":"def is_valid_auth_mode(settings: dict | None) -> bool:\n    return settings is None or settings.get(\"mode\") in {\"on\", \"off\", \"auto\"}","tryCatchPattern":"try:\n    await enterprise_custom_auth(request, api_key)\nexcept ValueError as e:\n    if str(e).startswith(\"Invalid mode:\"):\n        # fail closed: reject request, alert on config error\n        raise HTTPException(status_code=500, detail=\"auth config error\")\n    raise","preventionTips":["Validate proxy config in CI (yaml schema/lint) before deploy","Use only lowercase 'on' | 'off' | 'auto' for custom_auth_settings.mode","Add unit tests over the config loader asserting accepted modes"],"tags":["litellm","custom-auth","configuration","valueerror","mode"],"backgroundTag":"invalid-config-value","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}