BerriAI/litellm · error · Exception

Database not connected. Connect a database to your proxy - h

Error message

Database not connected. Connect a database to your proxy - https://docs.litellm.ai/docs/simple_proxy#managing-auth---virtual-keys

What it means

Exception raised by LiteLLMDatabase._ensure_prisma_client when the proxy's global prisma_client is None — i.e. DATABASE_URL/database config was not provided, so the proxy is running without a Postgres database. The CloudZero export needs the spend analytics tables (daily user spend), which only exist when LiteLLM's database is connected and populated.

Source

Thrown at litellm/integrations/cloudzero/database.py:35

# CHANGELOG: 2025-01-19 - Initial database module for LiteLLM data extraction (erik.peterson)

"""Database connection and data extraction for LiteLLM."""

from datetime import datetime
from typing import Any, Final

import polars as pl


class LiteLLMDatabase:
    """Handle LiteLLM PostgreSQL database connections and queries."""

    def _ensure_prisma_client(self):
        from litellm.proxy.proxy_server import prisma_client

        """Ensure prisma client is available."""
        if prisma_client is None:
            raise Exception(
                "Database not connected. Connect a database to your proxy - https://docs.litellm.ai/docs/simple_proxy#managing-auth---virtual-keys"
            )
        return prisma_client

    async def get_usage_data(
        self,
        limit: int | None = None,
        start_time_utc: datetime | None = None,
        end_time_utc: datetime | None = None,
    ) -> pl.DataFrame:
        """Retrieve usage data from LiteLLM daily user spend table."""
        client: Final = self._ensure_prisma_client()

        # Query to get user spend data with team information. Use parameter binding to
        # avoid SQL injection from user-supplied timestamps or limits.
        query = """
        SELECT
            dus.id,

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Connect a Postgres database: set DATABASE_URL (or database.url in config.yaml) and restart the proxy so prisma_client initializes
2. Verify the proxy logs show successful Prisma connection at startup
3. Ensure the proxy has run long enough for spend rows to accumulate before exporting
4. If you intentionally run without a database, disable the CloudZero export schedule

Example fix

# before
# config.yaml with cloudzero export but no database
litellm_settings:
  callbacks: [cloudzero]

# after
litellm_settings:
  callbacks: [cloudzero]
database_url: os.environ/DATABASE_URL  # Postgres backing the spend tables

def database_connected() -> bool:
    from litellm.proxy.proxy_server import prisma_client
    return prisma_client is not None

if not database_connected():
    raise RuntimeError("CloudZero export requires a connected Postgres database (set DATABASE_URL)")

def has_prisma_client() -> bool:
    """True when the proxy initialized its Prisma connection."""
    from litellm.proxy.proxy_server import prisma_client
    return prisma_client is not None

try:
    df = await db.get_usage_data(limit=1000)
except Exception as e:
    if "Database not connected" in str(e):
        skip_export_until_db_configured()
    else:
        raise

When it happens

Trigger: Running the LiteLLM proxy with no database (config.yaml lacks database: url / DATABASE_URL unset) while the cloudzero export job or another consumer of LiteLLMDatabase tries to query usage data; or checking the endpoint before proxy startup completed the Prisma connection.

Common situations: Trying CloudZero cost exports on a lightweight local proxy setup that stores spend in a JSON file instead of Postgres; misconfigured DATABASE_URL in Kubernetes so the proxy silently started in no-DB mode.

Related errors

• Error retrieving usage data: {e}
• Error saving email settings to general_settings: {str(e)}
• Database not connected
• DB not connected. This endpoint needs a database; set DATABA
• DB not connected. This endpoint needs a database; set DATABA

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