{"record":{"id":"e19ac7639ba15f42","repo":"BerriAI/litellm","slug":"urn-litellm-error-database-not-connected","errorCode":"urn:litellm:error:database-not-connected","errorMessage":"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","messagePattern":"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","errorType":"http","errorClass":"ManagementProblem","httpStatus":503,"severity":"error","filePath":"litellm/proxy/management_endpoints/management_v1/budgets.py","lineNumber":174,"sourceCode":"    `sort` takes a comma-separated list of `budget_id`, `max_budget`, `tpm_limit`,\n    `rpm_limit` or `created_at`, each optionally prefixed with `-` for descending,\n    and defaults to `-created_at`. `budget_id` is appended to every sort as the\n    tiebreaker. `q` is a case-insensitive substring match on `budget_id`.\n    `page_size` defaults to 50 and is capped at 100. Filters are\n    `filter[budget_duration][in|is_null]`, `filter[max_budget][gte|lte|is_null]`\n    and `filter[created_at][gte|lte]`.\n\n    Example curl:\n    ```\n    curl --location --globoff 'http://0.0.0.0:4000/management/v1/budgets?sort=-max_budget&filter[budget_duration][in]=7d,30d&page_size=25' \\\n        --header 'Authorization: Bearer sk-1234'\n    ```\n    \"\"\"\n    try:\n        from litellm.proxy.proxy_server import prisma_client\n\n        if prisma_client is None:\n            raise ManagementProblem(\n                ProblemDetail(\n                    type=f\"{PROBLEM_TYPE_BASE}database-not-connected\",\n                    title=\"Database not connected\",\n                    status=503,\n                    detail=CommonProxyErrors.db_not_connected_error.value,\n                )\n            )\n\n        return await handle_list(\n            spec=BUDGETS_LIST_SPEC,\n            executor=PrismaBudgetListExecutor(prisma_client=prisma_client),\n            request=request,\n            caller=user_api_key_dict,\n        )\n\n    except ManagementProblem:\n        raise\n    except Exception as e:  # noqa: BLE001  # a driver error answers as a problem document, not the OpenAI error shape","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/management_endpoints/management_v1/budgets.py#L156-L192","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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"],"exampleFix":"# before\n$ litellm --config config.yaml   # no DB\n$ curl :4000/management/v1/budgets\n# -> 503 {\"type\":\"urn:litellm:error:database-not-connected\",\"title\":\"Database not connected\", ...}\n# after\n$ export DATABASE_URL='postgresql://user:pass@db:5432/litellm'\n$ litellm --migrate && litellm --config config.yaml\n$ curl :4000/management/v1/budgets   # 200 with data + links","handlingStrategy":"validation","validationCode":"import os\n\ndef assert_management_db_ready() -> None:\n    assert os.getenv('DATABASE_URL', '').startswith(('postgresql://', 'postgres://')), (\n        'management/v1 endpoints are DB-backed: set DATABASE_URL before using them'\n    )\n\nasync def proxy_has_db(client: httpx.AsyncClient) -> bool:\n    r = await client.get('/management/v1/budgets')\n    return not (r.status_code == 503 and 'database-not-connected' in r.text)","typeGuard":null,"tryCatchPattern":"try:\n    r = await client.get('/management/v1/budgets', params=q)\n    r.raise_for_status()\nexcept httpx.HTTPStatusError as e:\n    problem = e.response.json()\n    if problem.get('type', '').endswith('database-not-connected'):\n        raise RuntimeError('proxy has no database attached — config error, not retryable') from e\n    raise","preventionTips":["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"],"tags":["database","configuration","problem-details","litellm-proxy","budgets","management-api"],"backgroundTag":"database-not-connected","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","schemaVersion":2},"datasetVersion":"2026-08-21T13:17:26.733Z"}