BerriAI/litellm · error · HTTPException

Prisma client not initialized

Error message

Prisma client not initialized

What it means

POST /guardrails raises HTTP 500 'Prisma client not initialized' when the proxy global prisma_client is None, i.e. the proxy was started without a database. Guardrails are persisted in the DB (guardrails table) and hot-synced into memory, so a DB is mandatory for this endpoint.

Source

Thrown at litellm/proxy/guardrails/guardrail_endpoints.py:403

        "guardrail_info": {
            "description": "Bedrock content moderation guardrail"
        },
        "created_at": "2023-11-09T12:34:56.789Z",
        "updated_at": "2023-11-09T12:34:56.789Z"
    }
    ```
    """
    from litellm.proxy.guardrails.guardrail_registry import IN_MEMORY_GUARDRAIL_HANDLER
    from litellm.proxy.proxy_server import prisma_client

    if user_api_key_dict.user_role != LitellmUserRoles.PROXY_ADMIN:
        raise HTTPException(
            status_code=403,
            detail="Admin access required to manage guardrails",
        )

    if prisma_client is None:
        raise HTTPException(status_code=500, detail="Prisma client not initialized")

    try:
        result = await GUARDRAIL_REGISTRY.add_guardrail_to_db(guardrail=request.guardrail, prisma_client=prisma_client)

        guardrail_name: Final = result.get("guardrail_name", "Unknown")
        guardrail_id: Final = result.get("guardrail_id", "Unknown")

        try:
            IN_MEMORY_GUARDRAIL_HANDLER.initialize_guardrail(guardrail=cast(Guardrail, result), source="db")
            verbose_proxy_logger.info(
                "Immediate sync: Successfully initialized guardrail '%s' (ID: %s)", guardrail_name, guardrail_id
            )
        except (ValueError, TypeError) as init_error:
            # Configuration error — roll back the DB write so the guardrail isn't orphaned
            if prisma_client is not None:
                try:
                    await _delete_guardrail_row(prisma_client, where={"guardrail_id": guardrail_id})
                except Exception as rollback_err:

View on GitHub (pinned to 77b7c6c40c)

Solutions

  1. Set DATABASE_URL to a reachable Postgres instance in the proxy environment and restart (LiteLLM auto-runs migrations on startup)
  2. If using docker, ensure the env var is passed: docker run -e DATABASE_URL=postgresql://...
  3. Verify with GET /health/liveliness and proxy startup logs that Prisma connected before retrying
  4. If you only need static guardrails, define them under guardrails: in config.yaml instead of the API — no DB needed at runtime for config-declared guardrails

Example fix

# before
litellm --config config.yaml  # no DATABASE_URL
curl -X POST http://localhost:4000/guardrails ...  # 500

# after
export DATABASE_URL="postgresql://user:pass@host:5432/litellm"
litellm --config config.yaml
curl -X POST http://localhost:4000/guardrails -H 'Authorization: Bearer sk-master-key' ...
Defensive patterns

Strategy: validation

Validate before calling

import os, requests

if not os.environ.get("DATABASE_URL"):
    raise RuntimeError("Proxy needs DATABASE_URL before guardrail CRUD")
health = requests.get(f"{proxy}/health/liveliness", timeout=5)
health.raise_for_status()

Try / catch

try:
    r = requests.post(f"{proxy}/guardrails", json=guardrail, headers=h, timeout=30)
    r.raise_for_status()
except requests.HTTPError as e:
    if e.response is not None and e.response.status_code == 500 and "Prisma" in e.response.text:
        raise RuntimeError("Proxy is DB-less; set DATABASE_URL and restart, or define guardrails in config.yaml") from e
    raise

Prevention

When it happens

Trigger: Starting litellm proxy without DATABASE_URL (or with database: None in config) and then calling POST /guardrails.

Common situations: Local dev servers run in zero-config mode for chat completions only; Kubernetes deployment missing the DATABASE_URL secret; Postgres URL typo so prisma_client construction was skipped; hitting management endpoints on a UI-less headless instance.

Related errors

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