{"record":{"id":"6c257fa3d2cdb19e","repo":"BerriAI/litellm","slug":"database-not-connected-6c257f","errorCode":null,"errorMessage":"Database not connected","messagePattern":"Database not connected","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"critical","filePath":"litellm/proxy/management_endpoints/key_management_endpoints.py","lineNumber":2159,"sourceCode":"async def _get_and_validate_existing_key(\n    token: str | None, prisma_client: PrismaClient | None, key_alias: str | None = None\n) -> LiteLLM_VerificationToken:\n    \"\"\"\n    Get existing key from database and validate it exists.\n\n    Args:\n        token: The key token to look up\n        prisma_client: Prisma client instance\n        key_alias: Alias to look the key up by when token is not provided\n\n    Returns:\n        LiteLLM_VerificationToken: The existing key row\n\n    Raises:\n        ProxyException: 404 if key is not found, 400 if the alias matches multiple keys\n    \"\"\"\n    if prisma_client is None:\n        raise HTTPException(\n            status_code=500,\n            detail={\"error\": \"Database not connected\"},\n        )\n\n    if token is not None:\n        hashed_token: Final = _hash_token_if_needed(token=token)\n\n        existing_key_row: Final[LiteLLM_VerificationToken | None] = await _prisma_table(\n            VerificationTokenRepository(prisma_client)\n        ).find_unique(where={\"token\": hashed_token})\n\n        if existing_key_row is None:\n            raise ProxyException(\n                message=\"Key not found.\",\n                type=ProxyErrorTypes.not_found_error,\n                param=\"key\",\n                code=status.HTTP_404_NOT_FOUND,\n            )","sourceCodeStart":2141,"sourceCodeEnd":2177,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/management_endpoints/key_management_endpoints.py#L2141-L2177","documentation":"Every key-lookup flow in this module funnels through _get_and_validate_existing_key, which requires the Prisma client; if the proxy started without a database connection the helper raises HTTP 500 'Database not connected' before any query. It means the running proxy instance has prisma_client None (no DATABASE_URL / failed init), so /key/update, /key/info, and similar endpoints cannot function.","triggerScenarios":"Calling POST /key/update (by key or key_alias) on a proxy started without general_settings.database_url/DATABASE_URL; database URL configured but initialization failed silently at boot; multiple proxy replicas where one was scheduled without the env var; hitting a management endpoint on a config-only instance meant purely for model routing.","commonSituations":"Local experimentation with litellm as a gateway only, then trying key management; Helm chart with DATABASE_URL defined in a secret the pod didn't mount; DB outage during startup left the proxy up but client-less.","solutions":["Configure DATABASE_URL=postgresql://... (env var or config.yaml general_settings.database_url) and restart the proxy","Check startup logs for Prisma connection errors if the URL was already set","Run the documented migration step so the LiteLLM_ProxyModel tables exist","Point management-API traffic at a proxy instance that actually has the DB configured"],"exampleFix":"# before (run proxy with only model config)\n$ litellm --config config.yaml  # no DATABASE_URL\n\n# after\n$ export DATABASE_URL=postgresql://litellm:pw@postgres:5432/litellm\n$ litellm --config config.yaml","handlingStrategy":"validation","validationCode":"# deployment check: proxy must expose DB-backed endpoints\nr = await client.get(\"/key/list\")\nif r.status_code == 500 and \"Database not connected\" in r.text:\n    raise RuntimeError(\"target proxy has no DATABASE_URL; aborting key management calls\")","typeGuard":null,"tryCatchPattern":"try:\n    r = await client.post(\"/key/update\", json=payload)\nexcept httpx.HTTPStatusError as e:\n    if e.response.status_code == 500 and \"Database not connected\" in e.response.text:\n        raise RuntimeError(\"configure DATABASE_URL on the proxy; retrying won't help\") from e\n    raise","preventionTips":["Gate key-management automation on a /key/list health probe so you fail before mutating anything","Bake DATABASE_URL into every proxy deployment manifest that serves management APIs","Verify Prisma connected at boot via startup logs, not just process liveness"],"tags":["litellm","proxy","database","prisma","configuration"],"backgroundTag":"database-not-connected","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}