BerriAI/litellm · error · ManagementProblem

urn:litellm:error:database-not-connected

urn:litellm:error:database-not-connected

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

The v1 management API returns RFC 9457 problem documents, and this 503 problem (type urn:litellm:error:database-not-connected) is GET /management/v1/budgets's response when prisma_client is None. Unlike the legacy endpoints' bare 500 Exceptions, here the failure is a structured ProblemDetail with status 503, so clients can branch on 'type' cleanly.

Source

Thrown at litellm/proxy/management_endpoints/management_v1/budgets.py:174

    `sort` takes a comma-separated list of `budget_id`, `max_budget`, `tpm_limit`,
    `rpm_limit` or `created_at`, each optionally prefixed with `-` for descending,
    and defaults to `-created_at`. `budget_id` is appended to every sort as the
    tiebreaker. `q` is a case-insensitive substring match on `budget_id`.
    `page_size` defaults to 50 and is capped at 100. Filters are
    `filter[budget_duration][in|is_null]`, `filter[max_budget][gte|lte|is_null]`
    and `filter[created_at][gte|lte]`.

    Example curl:
    ```
    curl --location --globoff 'http://0.0.0.0:4000/management/v1/budgets?sort=-max_budget&filter[budget_duration][in]=7d,30d&page_size=25' \
        --header 'Authorization: Bearer sk-1234'
    ```
    """
    try:
        from litellm.proxy.proxy_server import prisma_client

        if prisma_client is None:
            raise ManagementProblem(
                ProblemDetail(
                    type=f"{PROBLEM_TYPE_BASE}database-not-connected",
                    title="Database not connected",
                    status=503,
                    detail=CommonProxyErrors.db_not_connected_error.value,
                )
            )

        return await handle_list(
            spec=BUDGETS_LIST_SPEC,
            executor=PrismaBudgetListExecutor(prisma_client=prisma_client),
            request=request,
            caller=user_api_key_dict,
        )

    except ManagementProblem:
        raise
    except Exception as e:  # noqa: BLE001  # a driver error answers as a problem document, not the OpenAI error shape

View on GitHub (pinned to 77b7c6c40c)

Solutions

Configure DATABASE_URL='postgresql://...' and restart the proxy
Run migrations so budget tables exist: litellm --migrate
Branch client-side on problem type 'database-not-connected' (503) to distinguish setup errors from bad requests (400)
Use the provided docker-compose Postgres if you need a quick supported setup

Example fix

# before
$ litellm --config config.yaml   # no DB
$ curl :4000/management/v1/budgets
# -> 503 {"type":"urn:litellm:error:database-not-connected","title":"Database not connected", ...}
# after
$ export DATABASE_URL='postgresql://user:pass@db:5432/litellm'
$ litellm --migrate && litellm --config config.yaml
$ curl :4000/management/v1/budgets   # 200 with data + links

Defensive patterns

Strategy: validation

Validate before calling

import os

def assert_management_db_ready() -> None:
    assert os.getenv('DATABASE_URL', '').startswith(('postgresql://', 'postgres://')), (
        'management/v1 endpoints are DB-backed: set DATABASE_URL before using them'
    )

async def proxy_has_db(client: httpx.AsyncClient) -> bool:
    r = await client.get('/management/v1/budgets')
    return not (r.status_code == 503 and 'database-not-connected' in r.text)

Try / catch

try:
    r = await client.get('/management/v1/budgets', params=q)
    r.raise_for_status()
except httpx.HTTPStatusError as e:
    problem = e.response.json()
    if problem.get('type', '').endswith('database-not-connected'):
        raise RuntimeError('proxy has no database attached — config error, not retryable') from e
    raise

Prevention

Branch on the problem 'type' URN rather than the detail text for v1 management errors
Wire DATABASE_URL and migrations into the same deployment step that exposes management/v1
Add a startup smoke test that hits a management list endpoint

When it happens

Trigger: curl 'http://0.0.0.0:4000/management/v1/budgets?sort=-max_budget' against a proxy started without DATABASE_URL; Prisma failed at startup; the management API was routed to a DB-less proxy replica.

Common situations: Evaluating the new management/v1 surface on a minimal deployment; docker-compose where the db service is unhealthy; forgetting that budgets are DB-only objects (unlike config-file models).

Related errors

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