BerriAI/litellm · error · HTTPException

Database not connected. Please connect a database.

Error message

Database not connected. Please connect a database.

What it means

POST /cache/settings persists new cache settings (encrypting sensitive fields) to LiteLLM_CacheConfig and reinitializes the cache. It hard-requires a database: if prisma_client is None it raises HTTP 500 'Database not connected. Please connect a database.' before touching anything. Unlike most management endpoints this check happens with a 500 status, because persisting settings is a server-side capability requirement, not a client request problem.

Source

Thrown at litellm/proxy/management_endpoints/cache_settings_endpoints.py:595

        description="The litellm-changed-by header enables tracking of actions performed by authorized users on behalf of other users, providing an audit trail for accountability",
    ),
):
    """
    Save cache settings to database and initialize cache.

    This endpoint:
    1. Encrypts sensitive fields (passwords, etc.)
    2. Saves to LiteLLM_CacheConfig table
    3. Reinitializes cache with new settings
    """
    from litellm.proxy.proxy_server import (
        prisma_client,
        proxy_config,
        store_model_in_db,
    )

    if prisma_client is None:
        raise HTTPException(
            status_code=500,
            detail={"error": "Database not connected. Please connect a database."},
        )

    if store_model_in_db is not True:
        raise HTTPException(
            status_code=500,
            detail={"error": "Set `'STORE_MODEL_IN_DB='True'` in your env to enable this feature."},
        )

    try:
        # Read the stored row first: its decrypted values back any credential the
        # caller echoed back redacted, and its key set drives the audit diff.
        existing_row: Final = await _cache_config_table(prisma_client).find_unique(where={"id": "cache_config"})
        before_settings: dict[str, object] | None = None
        saved_settings: dict[str, object] = {}
        if existing_row is not None and existing_row.cache_settings:
            before_settings = _parse_stored_settings(existing_row.cache_settings)

View on GitHub (pinned to 77b7c6c40c)

Solutions

  1. Provision PostgreSQL and set DATABASE_URL="postgresql://...", then restart the proxy
  2. Verify with GET /cache/settings (which reads current values) that the DB-backed flow works end-to-end
  3. Then re-POST the settings; note the companion requirement STORE_MODEL_IN_DB=True for this same endpoint (see the next error)

Example fix

# before: no DATABASE_URL
litellm --config config.yaml  # POST /cache/settings -> 500 Database not connected

# after
export DATABASE_URL="postgresql://user:pass@db:5432/litellm"
litellm --config config.yaml  # POST /cache/settings -> 200
Defensive patterns

Strategy: validation

Validate before calling

import os

# /cache/settings (POST) needs BOTH a DB and the store-model flag
assert os.getenv("DATABASE_URL", "").startswith("postgresql://"), "DB required"
assert os.getenv("STORE_MODEL_IN_DB", "").lower() == "true", "STORE_MODEL_IN_DB=True required"

Try / catch

import httpx

try:
    r = httpx.post(f"{PROXY_URL}/cache/settings", json=settings, headers=hdrs)
    r.raise_for_status()
except httpx.HTTPStatusError as e:
    detail = e.response.json().get("detail", {})
    if e.response.status_code == 500 and "Database not connected" in str(detail):
        raise RuntimeError("set DATABASE_URL and restart the proxy") from e
    raise

Prevention

When it happens

Trigger: POST /cache/settings with a settings payload against a proxy launched without DATABASE_URL; trying to configure Redis caching through the Admin UI on a config-only deployment.

Common situations: Attempting UI-driven cache configuration on a lightweight proxy without Postgres; DATABASE_URL not propagated to the container that hosts the settings endpoint; evaluating cache features before standing up the production database.

Related errors

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