BerriAI/litellm · critical · HTTPException

Database not connected

Error message

Database not connected

What it means

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.

Source

Thrown at litellm/proxy/management_endpoints/key_management_endpoints.py:2159

async def _get_and_validate_existing_key(
    token: str | None, prisma_client: PrismaClient | None, key_alias: str | None = None
) -> LiteLLM_VerificationToken:
    """
    Get existing key from database and validate it exists.

    Args:
        token: The key token to look up
        prisma_client: Prisma client instance
        key_alias: Alias to look the key up by when token is not provided

    Returns:
        LiteLLM_VerificationToken: The existing key row

    Raises:
        ProxyException: 404 if key is not found, 400 if the alias matches multiple keys
    """
    if prisma_client is None:
        raise HTTPException(
            status_code=500,
            detail={"error": "Database not connected"},
        )

    if token is not None:
        hashed_token: Final = _hash_token_if_needed(token=token)

        existing_key_row: Final[LiteLLM_VerificationToken | None] = await _prisma_table(
            VerificationTokenRepository(prisma_client)
        ).find_unique(where={"token": hashed_token})

        if existing_key_row is None:
            raise ProxyException(
                message="Key not found.",
                type=ProxyErrorTypes.not_found_error,
                param="key",
                code=status.HTTP_404_NOT_FOUND,
            )

View on GitHub (pinned to 77b7c6c40c)

Solutions

  1. Configure DATABASE_URL=postgresql://... (env var or config.yaml general_settings.database_url) and restart the proxy
  2. Check startup logs for Prisma connection errors if the URL was already set
  3. Run the documented migration step so the LiteLLM_ProxyModel tables exist
  4. Point management-API traffic at a proxy instance that actually has the DB configured

Example fix

# before (run proxy with only model config)
$ litellm --config config.yaml  # no DATABASE_URL

# after
$ export DATABASE_URL=postgresql://litellm:pw@postgres:5432/litellm
$ litellm --config config.yaml
Defensive patterns

Strategy: validation

Validate before calling

# deployment check: proxy must expose DB-backed endpoints
r = await client.get("/key/list")
if r.status_code == 500 and "Database not connected" in r.text:
    raise RuntimeError("target proxy has no DATABASE_URL; aborting key management calls")

Try / catch

try:
    r = await client.post("/key/update", json=payload)
except httpx.HTTPStatusError as e:
    if e.response.status_code == 500 and "Database not connected" in e.response.text:
        raise RuntimeError("configure DATABASE_URL on the proxy; retrying won't help") from e
    raise

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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