BerriAI/litellm · critical · Exception

Database not connected. Connect a database to your proxy - h

Error message

Database not connected. Connect a database to your proxy - https://docs.litellm.ai/docs/simple_proxy#managing-auth---virtual-keys

What it means

POST /v2/key/info (batched key info lookup) needs the Prisma DB because key records live there. The handler checks prisma_client at call time and raises this Exception (rendered as a 500-family error) when the proxy has no database configured. The message links the docs for attaching a database, since virtual-key management is fundamentally a DB-backed feature.

Source

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

    **New endpoint**. Currently admin only.
    Parameters:
        keys: Optional[list] = body parameter representing the key(s) in the request
        user_api_key_dict: UserAPIKeyAuth = Dependency representing the user's API key
    Returns:
        Dict containing the key and its associated information

    Example Curl:
    ```
    curl -X GET "http://0.0.0.0:4000/key/info" \
    -H "Authorization: Bearer sk-1234" \
    -d {"keys": ["sk-1", "sk-2", "sk-3"]}
    ```
    """
    from litellm.proxy.proxy_server import prisma_client, user_api_key_cache

    try:
        if prisma_client is None:
            raise Exception(
                "Database not connected. Connect a database to your proxy - https://docs.litellm.ai/docs/simple_proxy#managing-auth---virtual-keys"
            )
        if data is None:
            raise HTTPException(
                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
                detail={"message": "Malformed request. No keys passed in."},
            )

        # Resolve key_aliases to tokens so we never pass token=None (unbounded query)
        tokens_to_query: Final = list(data.keys) if data.keys else []
        if data.key_aliases:
            alias_rows: Final = await _prisma_table(VerificationTokenRepository(prisma_client)).find_many(
                where={"key_alias": {"in": data.key_aliases}},
                include={"litellm_budget_table": True},
            )
            alias_tokens: Final = [row.token for row in alias_rows if row.token]
            tokens_to_query.extend(alias_tokens)

View on GitHub (pinned to 77b7c6c40c)

Solutions

Configure and restart with a Postgres database: set DATABASE_URL env var or database_connection.url in the config YAML.
Confirm the variable is visible to the running process (docker exec env | grep DATABASE_URL, or pod exec).
Until a DB is attached, expect all key endpoints (/key/info, /key/generate, /key/delete) to fail the same way — this is a deployment gap, not a per-call issue.

Example fix

# before
# docker-compose.yml service has no DATABASE_URL

# after
services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    environment:
      DATABASE_URL: postgresql://user:pass@db:5432/litellm
    command: ["--config", "/app/config.yaml"]

Defensive patterns

Strategy: validation

Validate before calling

if not os.environ.get("DATABASE_URL"):
    raise RuntimeError("cannot query /v2/key/info: litellm proxy needs a Postgres DB (DATABASE_URL)")
resp = client.post("/v2/key/info", json={"keys": ["sk-1"]})

Try / catch

try:
    resp = client.post("/v2/key/info", json={"keys": keys})
    resp.raise_for_status()
except HTTPError as e:
    if "Database not connected" in e.response.text:
        fail_deploy("proxy started without DB; attach DATABASE_URL and restart")
    raise

Prevention

Gate any key-management integration behind a DB-required configuration assertion at startup.
Include DATABASE_URL in the deployment checklist for every environment that uses virtual keys.
Smoke-test a DB-backed endpoint post-deploy so misconfigurations surface before users do.

When it happens

Trigger: Calling POST /v2/key/info on a proxy started without DATABASE_URL / database_connection config; the DB env var not reaching the container/pod; config file loaded from a path lacking the database block.

Common situations: Trying key-management APIs on a config-only proxy meant purely for model routing; docker-compose that forgets to pass DATABASE_URL into the litellm service; DB secret present at build time but not runtime.

Related errors

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