{"record":{"id":"f1c7bf16c2191d67","repo":"BerriAI/litellm","slug":"service-unavailable-the-authentication-database-i","errorCode":null,"errorMessage":"Service Unavailable, the authentication database is temporarily unreachable. Please retry shortly.","messagePattern":"Service Unavailable, the authentication database is temporarily unreachable\\. Please retry shortly\\.","errorType":"http","errorClass":"HTTPException","httpStatus":503,"severity":"error","filePath":"litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py","lineNumber":1066,"sourceCode":"        if not MCPRequestHandler._admitted_key_is_active(key_object):\n            raise HTTPException(status_code=401, detail=\"Invalid or expired credential\")\n        await MCPRequestHandler._reject_if_admitted_owner_scim_deactivated(key_object)\n        return key_object\n\n    @staticmethod\n    def _raise_503_if_db_unavailable(e: Exception) -> None:\n        \"\"\"Raise a retryable 503 when ``e`` means the auth database is unreachable, else return so the\n        caller applies its own fail-closed mapping. A DB outage must not masquerade as an auth failure\n        (401) or surface as an opaque 500; the caller retries. Mirrors ``UserAPIKeyAuthExceptionHandler``,\n        which renders a service-unavailable database error as 503 on the standard pipeline.\n\n        Classifies across the ``__cause__``/``__context__`` chain, not just ``e`` itself: ``get_user_object``\n        re-raises every DB failure as a bare ``ValueError``, so a type-based check on the top exception\n        would miss a real outage wrapped inside it.\"\"\"\n        from litellm.proxy.db.exception_handler import PrismaDBExceptionHandler\n\n        if PrismaDBExceptionHandler.is_database_service_unavailable_error_in_chain(e):\n            raise HTTPException(\n                status_code=503,\n                detail=\"Service Unavailable, the authentication database is temporarily unreachable. Please retry shortly.\",\n            ) from None\n\n    @staticmethod\n    async def _reject_if_admitted_owner_scim_deactivated(key_object: UserAPIKeyAuth) -> None:\n        \"\"\"Fail closed with a 401 when the key's owning user was deactivated via SCIM.\n\n        The standard pipeline enforces this inline in ``_user_api_key_auth_builder`` rather\n        than in ``common_checks``, so the centralized policy gate does not cover it; without\n        this mirror, IdP offboarding would leave the user's already-minted envelopes live\n        until expiry. A failed user lookup skips the gate (fail-open), matching the builder:\n        this is the one deliberately fail-open check in an otherwise fail-closed arm, so a\n        transient DB outage during this lookup admits the request rather than rejecting it,\n        keeping parity with how the standard pipeline treats the same lookup failure.\"\"\"\n        if key_object.user_id is None:\n            return\n        from litellm.proxy.auth.auth_checks import get_user_object","sourceCodeStart":1048,"sourceCodeEnd":1084,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py#L1048-L1084","documentation":"HTTP 503 raised by the DB-availability mapper when the caught exception indicates the auth database is unreachable: it is deliberately surfaced as a retryable Service Unavailable rather than a misleading 401 auth failure or opaque 500.","triggerScenarios":"Thrown at litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py:1066 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Retry shortly; check database health and connectivity.","If persistent, fail over or restore the auth database."],"exampleFix":"Retry with exponential backoff; check DB logs.","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}