What causes "GCP IAM authentication failed" in BerriAI/litellm?

Grant the connecting identity the Redis IAM auth role: gcloud projects add-iam-policy-binding ... --role=roles/redis.instanceUser --member=...

BerriAI/litellm · error · AuthenticationError

GCP IAM authentication failed

Error message

GCP IAM authentication failed

What it means

litellm's Redis layer supports GCP Memorystore IAM auth: the connection function sends an AUTH command with an IAM-derived token and expects the server to answer 'OK'. If the response is anything else, redis.AuthenticationError('GCP IAM authentication failed') is raised — the token was accepted syntactically but the server rejected it (or the handshake produced a non-OK reply).

Solutions

Grant the connecting identity the Redis IAM auth role: gcloud projects add-iam-policy-binding ... --role=roles/redis.instanceUser --member=...
Verify the identity in use: gcloud auth application-default print-identity-token / check the SA attached to your workload
Confirm Memorystore instance has IAM auth enabled and you connect over TLS on port 6379 from an authorized network
Provide a valid gcp_service_account (path/JSON) in the Redis cache config, or fall back to ACL/password auth by supplying a password

Example fix

# before
RedisCache(host="10.x.x.x", port=6379, gcp_service_account="/secrets/sa.json")
# SA lacks IAM role -> AuthenticationError: GCP IAM authentication failed

# after
gcloud projects add-iam-policy-binding my-proj \
  --member="serviceAccount:proxy@my-proj.iam.gserviceaccount.com" \
  --role="roles/redis.instanceUser"
# then retry connection

Defensive patterns

Strategy: try-catch

Validate before calling

import redis

def can_auth_memorystore(host: str, port: int = 6379) -> bool:
    """Cheap pre-flight: server reachable + RESP AUTH path alive."""
    try:
        with redis.Redis(host=host, port=port, ssl=True, socket_connect_timeout=5):
            return True
    except (redis.ConnectionError, redis.AuthenticationError):
        return False

Try / catch

from redis.exceptions import AuthenticationError

try:
    cache = RedisCache(host=..., port=6379, gcp_service_account="/secrets/sa.json")
    cache.ping()
except AuthenticationError as e:
    if "GCP IAM" in str(e):
        raise RuntimeError(
            "Memorystore IAM rejected credentials: grant roles/redis.instanceUser "
            "to the connecting service account"
        ) from e
    raise

Prevention

Run `gcloud projects get-iam-policy` pre-deploy to assert the workload SA has roles/redis.instanceUser
Add a startup Redis ping to the proxy health check so auth failures surface at boot, not mid-request
Keep the SA key file readable only by the proxy process and rotate it; test with ADC in dev first

When it happens

Trigger: Connecting to Memorystore for Redis with IAM auth enabled where the workload's service account lacks the Redis IAM role (e.g. roles/redis.instanceUser / redis Enterprise Admin), or gcp_service_account credentials are wrong/expired; also when the fallback to password auth is unavailable (no password set) and IAM failed.

Common situations: Running the proxy on GKE/Cloud Run/Compute with Application Default Credentials of a SA missing Redis permissions; locally with a user creds that is not authorized on the instance; IAM enabled on the instance but connecting with a token for a different identity; clock skew breaking signed tokens.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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

Appendix: source

Thrown at litellm/_redis.py:209

        from redis.utils import str_if_bytes

        self._parser.on_connect(self)

        auth_args: Final = (_generate_gcp_iam_access_token(service_account),)
        self.send_command("AUTH", *auth_args, check_health=False)

        try:
            auth_response = self.read_response()
        except AuthenticationWrongNumberOfArgsError:
            # Fallback to password auth if IAM fails
            if hasattr(self, "password") and self.password:
                self.send_command("AUTH", self.password, check_health=False)
                auth_response = self.read_response()
            else:
                raise

        if str_if_bytes(auth_response) != "OK":
            raise AuthenticationError("GCP IAM authentication failed")

    return iam_connect


def _build_azure_credential(
    azure_client_id: str | None = None,
    azure_tenant_id: str | None = None,
    azure_client_secret: str | None = None,
):
    """
    Build a long-lived Azure credential object.

    Azure SDK credentials cache tokens internally and handle expiry/refresh
    transparently, so this should be called once and the result reused.
    """
    try:
        from azure.identity import (
            ClientSecretCredential,

View on GitHub (pinned to 77b7c6c40c)