BerriAI/litellm · error · Exception

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

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

LiteLLM's CloudZero integration reads usage rows from the proxy's PostgreSQL spend tables through the Prisma client stored on litellm.proxy.proxy_server.prisma_client. LiteLLMDatabase._ensure_prisma_client() raises this generic Exception when that module-global is None, meaning the proxy was never started with a database connected. Every CloudZero usage export fails until the proxy has initialized its Prisma connection.

Solutions

Set DATABASE_URL on the proxy (export DATABASE_URL=postgresql://user:pass@host:5432/litellm) and restart it so prisma_client is created
Or put the Postgres URL under the database: key of the proxy config YAML and start with litellm --config config.yaml
If exporting from a separate process, query the LiteLLM_DailyUserSpend table directly over Postgres instead of relying on the in-process prisma_client
Before exporting, assert the client exists: from litellm.proxy.proxy_server import prisma_client; if prisma_client is None: fail with a config error

Example fix

# before: export runs in a bare process with no proxy
from litellm.integrations.cloudzero.database import LiteLLMDatabase
df = await LiteLLMDatabase().get_usage_data()  # Exception: Database not connected...

# after: proxy started with a database first
# export DATABASE_URL=postgresql://user:pass@host:5432/litellm
# litellm --config config.yaml   (config contains database url)
from litellm.proxy.proxy_server import prisma_client
assert prisma_client is not None, "start the proxy with DATABASE_URL before exporting"
df = await LiteLLMDatabase().get_usage_data()

Defensive patterns

Strategy: validation

Validate before calling

from litellm.proxy.proxy_server import prisma_client

if prisma_client is None:
    raise RuntimeError("LiteLLM proxy has no database; set DATABASE_URL before running the CloudZero export")

df = await LiteLLMDatabase().get_usage_data(limit=1000)

Try / catch

try:
    df = await db.get_usage_data(...)
except Exception as e:
    if 'Database not connected' in str(e):
        raise RuntimeError('start proxy with DATABASE_URL set') from e
    raise

Prevention

Always set DATABASE_URL in the proxy deployment environment
Gate export jobs on a proxy health endpoint that reports database status
Fail startup checks when prisma_client is None after proxy boot

When it happens

Trigger: Awaiting LiteLLMDatabase().get_usage_data() in a process where the LiteLLM proxy was never started with DATABASE_URL set (prisma_client stays None); running the CloudZero export as a standalone script that imports litellm but never boots the proxy server; calling the export before the proxy's DB connection has finished initializing.

Common situations: Fresh deployment missing the DATABASE_URL env var; export job split from the proxy runtime so no proxy state exists in-process; typo'd or unset DATABASE_URL letting the proxy start DB-less; litellm version drift changing when prisma_client is populated.

Related errors

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

Appendix: 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 77b7c6c40c)