BerriAI/litellm · error · RuntimeError

{env_var} uses unsupported scheme '{scheme}'. LiteLLM's data

Error message

{env_var} uses unsupported scheme '{scheme}'. LiteLLM's database features (virtual keys, store_model_in_db, spend tracking) require PostgreSQL; use a 'postgresql://' connection string. SQLite and other engines are not supported. See https://docs.litellm.ai/docs/proxy/virtual_keys

What it means

Error "{env_var} uses unsupported scheme '{scheme}'. LiteLLM's database features (virtual keys, store_model_in_db, spend tracking) require PostgreSQL; use a 'postgresql://' connection string. SQLite and other engines are not supported. See https://docs.litellm.ai/docs/proxy/virtual_keys" thrown in BerriAI/litellm.

Source

Thrown at litellm/proxy/db/db_url_settings.py:272

    def _raise_for_unsupported_scheme(self) -> None:
        """Reject an operator-pinned non-PostgreSQL writer / direct / reader URL.

        The componentized entrypoints (gateway / backend / migrations) call
        ``apply_to_env`` and then hand the URL straight to Prisma, bypassing
        the CLI's own guard. A pinned URL flows through untouched, so validate
        the same three vars the CLI guard checks (DATABASE_URL, DIRECT_URL, and
        the read replica) rather than letting Prisma stall on an unusable scheme.
        """
        for env_var, url in (
            ("DATABASE_URL", self.database_url),
            ("DIRECT_URL", self.direct_url),
            ("DATABASE_URL_READ_REPLICA", self.database_url_read_replica),
        ):
            if not url:
                continue
            bad_scheme = unsupported_db_scheme(url)
            if bad_scheme is not None:
                raise RuntimeError(unsupported_db_scheme_message(env_var, bad_scheme))

    def apply_to_env(self) -> bool:
        """Write the assembled URL(s) into ``os.environ``.

        Returns True iff this call set ``DATABASE_URL`` (IAM mint, or
        password auth that assembled a fresh URL). False means there was
        nothing to do — an operator-pinned URL, or no discrete fields.
        """
        self._raise_for_unsupported_scheme()
        wrote_writer = False
        writer_url: Final = self.build_writer_url()
        if writer_url is not None:
            os.environ["DATABASE_URL"] = writer_url
            if self.iam_token_db_auth:
                # Normalize the toggle so downstream readers (PrismaWrapper's
                # IAM refresh) reliably see IAM on, regardless of spelling.
                os.environ[_IAM_ENV_KEY] = "True"
            wrote_writer = True

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Use a postgresql:// connection string for the named env var.
2. SQLite and other engines are not supported for LiteLLM database features.

Example fix

export DATABASE_URL=postgresql://user:pass@host:5432/litellm

When it happens

Trigger: Thrown at litellm/proxy/db/db_url_settings.py:272 when the library encounters an invalid state.

Common situations: The database URL uses an unsupported scheme such as sqlite://.

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