BerriAI/litellm · critical · 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

Project endpoints persist state in PostgreSQL via Prisma; if the proxy booted without a DATABASE_URL, prisma_client is None and POST /project/new aborts with HTTP 500 and CommonProxyErrors.db_not_connected_error. This is a server-side configuration gap, not a bad request.

Source

Thrown at enterprise/litellm_enterprise/proxy/management_endpoints/project_endpoints.py:363

            raise HTTPException(
                status_code=403,
                detail={
                    "error": "Project management is an enterprise feature. " + CommonProxyErrors.not_premium_user.value
                },
            )

        # ADD METADATA FIELDS
        for field in LiteLLM_ManagementEndpoint_MetadataFields_Premium:
            if getattr(data, field, None) is not None:
                _set_object_metadata_field(
                    object_data=data,
                    field_name=field,
                    value=getattr(data, field),
                )
                delattr(data, field)

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

        # Validate team exists and get team object with budget
        team_object = await _validate_team_exists(team_id=data.team_id, prisma_client=prisma_client)

        # Validate project limits against team limits
        _check_team_project_limits(
            team_object=LiteLLM_TeamTable.model_validate(team_object.model_dump()),
            data=data,
        )

        # Check if user has permission to create projects for this team
        # only team admins can create projects for their team
        has_permission = await _check_user_permission_for_project(
            user_api_key_dict=user_api_key_dict,
            team_id=data.team_id,

View on GitHub (pinned to 6c2dcb801b)

Solutions

Set DATABASE_URL to a valid PostgreSQL connection string (postgresql://user:pass@host:5432/db) and restart the proxy
Confirm startup logs show the Prisma client connected before retrying
If running in Docker/K8s, verify the env var is injected into the proxy container itself

Example fix

# before
litellm --config config.yaml  # no DATABASE_URL
# after
export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/litellm
litellm --config config.yaml

Defensive patterns

Strategy: try-catch

Validate before calling

health = await client.get('/health/liveliness')
# or check that key management endpoints work, e.g. GET /key/list, as a DB proxy check
# DB presence is server-side; best client-side proxy is an admin health endpoint

Try / catch

catch (e) {
  if (e.status === 500 && /DB not connected/.test(e.body?.detail?.error ?? '')) {
    throw new Error('Proxy has no DATABASE_URL configured; set it and restart the proxy');
  }
  throw e;
}

Prevention

Always set DATABASE_URL when deploying with management endpoints; treat it as mandatory for enterprise features
Include a DB-backed health check in readiness probes so traffic only routes to DB-connected replicas

When it happens

Trigger: POST /project/new against a proxy started without DATABASE_URL (e.g. config-only mode with just a YAML of models), or where the DB connection failed at startup leaving prisma_client unset.

Common situations: Evaluating the proxy with a static config first and later trying management endpoints, DATABASE_URL typo'd or pointing at an unreachable Postgres, or forgetting to pass the env var into Docker.

Related errors

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/39c6bca2adfae6e7. Report an issue: GitHub.