BerriAI/litellm · error · RuntimeError

IAM_TOKEN_DB_AUTH is enabled and DATABASE_HOST_READ_REPLICA

Error message

IAM_TOKEN_DB_AUTH is enabled and DATABASE_HOST_READ_REPLICA is set, but the reader could not resolve: {', '.join(missing)} (no *_READ_REPLICA value and no writer fallback). Set the reader fields or the writer defaults.

What it means

Error "IAM_TOKEN_DB_AUTH is enabled and DATABASE_HOST_READ_REPLICA is set, but the reader could not resolve: {', '.join(missing)} (no *_READ_REPLICA value and no writer fallback). Set the reader fields or the writer defaults." thrown in BerriAI/litellm.

Source

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

        host: Final = self.database_host_read_replica
        port: Final = self.database_port_read_replica or self.database_port
        user = self.database_user_read_replica or self.database_user
        name = self.database_name_read_replica or self.database_name
        schema: Final = self.database_schema_read_replica or self.database_schema
        password: Final = self.database_password_read_replica or self.database_password

        if self.iam_token_db_auth:
            missing: Final = [
                env
                for env, val in (
                    ("DATABASE_USER[_READ_REPLICA]", user),
                    ("DATABASE_NAME[_READ_REPLICA]", name),
                )
                if not val
            ]
            if missing:
                raise RuntimeError(
                    "IAM_TOKEN_DB_AUTH is enabled and DATABASE_HOST_READ_REPLICA "
                    "is set, but the reader could not resolve: "
                    f"{', '.join(missing)} (no *_READ_REPLICA value and no "
                    "writer fallback). Set the reader fields or the writer "
                    "defaults."
                )
            user = cast(str, user)
            name = cast(str, name)
            token: Final = rds_iam_token.generate_iam_auth_token(db_host=host, db_port=port, db_user=user)
            url = f"postgresql://{user}:{token}@{host}:{port}/{name}"
            if schema:
                url += f"?schema={schema}"
            return url

        if user and name:
            return self._password_url(
                user=user,
                password=password,

View on GitHub (pinned to 77b7c6c40c)

Solutions

  1. Set the *_READ_REPLICA variants of the DB env vars, or set the writer defaults so the reader can fall back.

Example fix

export DATABASE_HOST_READ_REPLICA=... DATABASE_USER_READ_REPLICA=...
Defensive patterns

Strategy: validation

When it happens

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

Common situations: IAM_TOKEN_DB_AUTH with a read replica configured, but reader fields and writer fallbacks are both missing.

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