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

Raised by the enterprise audit-log listing endpoint. It performs Prisma JSON path filtering on object_team_id / object_key_hash (PostgreSQL-only) and returns HTTP 500 with CommonProxyErrors.db_not_connected_error when prisma_client is None. The message explicitly tells you to set DATABASE_URL to a PostgreSQL connection string.

Source

Thrown at enterprise/litellm_enterprise/proxy/audit_logging_endpoints.py:99

    # Sorting parameters
    sort_by: Optional[str] = Query(
        None,
        description="Column to sort by (e.g. 'updated_at', 'action', 'table_name')",
    ),
    sort_order: str = Query("desc", description="Sort order ('asc' or 'desc')"),
):
    """
    Get all audit logs with filtering and pagination.

    Returns a paginated response of audit logs matching the specified filters.

    Note: object_team_id and object_key_hash use Prisma JSON path filtering,
    which requires PostgreSQL.
    """
    from litellm.proxy.proxy_server import prisma_client

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

    # Build filter conditions
    where_conditions: Dict[str, Any] = {}
    if changed_by:
        where_conditions["changed_by"] = changed_by
    if changed_by_api_key:
        where_conditions["changed_by_api_key"] = changed_by_api_key
    if action:
        where_conditions["action"] = action
    if table_name:
        where_conditions["table_name"] = table_name
    if object_id:
        where_conditions["object_id"] = object_id
    if start_date or end_date:
        date_filter: Dict[str, Any] = {}

View on GitHub (pinned to 6c2dcb801b)

Solutions

Set DATABASE_URL (PostgreSQL) in env or config and restart the proxy
Run prisma migrations (litellm --config config.yaml --diagnose or the documented migration flow) so litellm_auditlog exists, then retry
Do not call audit endpoints on DB-less instances; monitor them separately

Example fix

# before
export MASTER_KEY=sk-123
litellm --config config.yaml
# GET /audit/logs -> 500

# after
export DATABASE_URL=postgresql://user:pass@host:5432/litellm
litellm --config config.yaml

Defensive patterns

Strategy: validation

Validate before calling

ready = httpx.get(f'{PROXY_URL}/health/readiness', headers=admin_headers)
if ready.status_code != 200:
    raise RuntimeError('Cannot list audit logs: proxy DB not ready')

Try / catch

try:
    logs = httpx.get(f'{PROXY_URL}/audit/logs', params=p, headers=admin_headers)
except httpx.HTTPStatusError as e:
    if 'db_not_connected' in e.response.text or 'DATABASE_URL' in e.response.text:
        raise InfrastructureError('proxy missing DATABASE_URL') from e
    raise

Prevention

Provision PostgreSQL as a hard dependency for deployments using audit logs
Add DB readiness gates to dashboards that call /audit/logs
Use IaC so DATABASE_URL is always set on audit-enabled environments

When it happens

Trigger: GET on /audit/logs (with optional filters like changed_by, action, date range) against a proxy without a database. The guard fires before any filter is built, so even an unfiltered list call triggers it.

Common situations: Exploring audit endpoints on a config-only proxy; DATABASE_URL omitted because the deployer assumed audit logs were optional; DB credentials rotated and the proxy restarted without the new URL.

Related errors

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