BerriAI/litellm · error · HTTPException

DB not connected. This endpoint needs a database; set DATABA

Error message

DB not connected. This endpoint needs a database; set DATABASE_URL to a PostgreSQL connection string (postgresql://...) to enable it. See https://docs.litellm.ai/docs/proxy/virtual_keys

What it means

/user/available_users (enterprise internal user management) requires Prisma/PostgreSQL. The handler imports prisma_client from proxy_server and immediately raises HTTP 500 with CommonProxyErrors.db_not_connected_error when it is None — i.e. the proxy started without DATABASE_URL so no database client was ever constructed.

Source

Thrown at enterprise/litellm_enterprise/proxy/management_endpoints/internal_user_endpoints.py:35

    dependencies=[Depends(user_api_key_auth)],
)
async def available_enterprise_users(
    user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth),
):
    """
    For keys with `max_users` set, return the list of users that are allowed to use the key.
    """
    from litellm.proxy._types import CommonProxyErrors, EnterpriseLicenseData
    from litellm.proxy.proxy_server import (
        premium_user,
        premium_user_data,
        prisma_client,
    )
    from litellm.repositories.team_repository import TeamRepository
    from litellm.repositories.user_repository import UserRepository

    if prisma_client is None:
        raise HTTPException(
            status_code=500,
            detail={"error": CommonProxyErrors.db_not_connected_error.value},
        )

    if not premium_user:
        # check if SSO is enabled - show 5 user limit
        from litellm.proxy.auth.auth_utils import _has_user_setup_sso

        if _has_user_setup_sso():
            premium_user_data = EnterpriseLicenseData(
                max_users=5,
            )

    user_count = await UserRepository(prisma_client).count_billable_users()
    team_count = await TeamRepository(prisma_client).count()

    if (
        not premium_user_data

View on GitHub (pinned to 77b7c6c40c)

Solutions

Set DATABASE_URL (or database_url in config.yaml) to a postgresql:// connection string and restart — LiteLLM connects and migrates on startup
Use the documented docker-compose setup with a postgres container for user/team management features
Confirm the DB is attached via /health/liveliness before calling user endpoints

Example fix

# before
docker run -p 4000:4000 ghcr.io/berriai/litellm --config /app/config.yaml  # no DATABASE_URL

# after
docker run -p 4000:4000 -e DATABASE_URL=postgresql://user:pass@host:5432/litellm ghcr.io/berriai/litellm --config /app/config.yaml

Defensive patterns

Strategy: validation

Validate before calling

import os

DB_REQUIRED = True
if DB_REQUIRED and not os.environ.get("DATABASE_URL", "").startswith("postgresql://"):
    raise SystemExit("DATABASE_URL must be a postgresql:// string for user management endpoints")

Try / catch

try:
    users = await client.get("/user/available_users")
except HTTPStatusError as e:
    if e.response.status_code == 500 and "db_not_connected" in e.response.text:
        # config error, not transient: fix DATABASE_URL and restart proxy
        raise RuntimeError("proxy needs DATABASE_URL set")
    raise

Prevention

Set DATABASE_URL in every environment that uses user/team/project management
Use the stock docker-compose with postgres instead of hand-rolled stateless setups
Health-check DB connectivity after deploys before smoke-testing management endpoints

When it happens

Trigger: GET /user/available_users on a proxy whose config lacks database_url / DATABASE_URL, so prisma_client is None at request time.

Common situations: Config written for stateless single-instance operation and then user-management endpoints called; docker run without passing DATABASE_URL into the container; a typo'd DB URL that silently prevented Prisma connect.

Related errors

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