BerriAI/litellm · error · ImportError

google-cloud-iam is required for GCP IAM Redis…

Error message

google-cloud-iam is required for GCP IAM Redis authentication. Install it with: pip install google-cloud-iam

What it means

LiteLLM can authenticate to Redis with short-lived GCP IAM access tokens instead of a static password, generating them via the iam_credentials_v1 client from the google-cloud-iam package. That package is optional (part of litellm's extra_proxy extra, not the base install). When token generation runs and 'from google.cloud import iam_credentials_v1' fails, this ImportError is raised with install instructions before any Redis connection is attempted.

Solutions

pip install google-cloud-iam (or pip install 'litellm[extra_proxy]', which pins google-cloud-iam>=2.19.1,<3.0) and restart the process
Verify the import: python -c "from google.cloud import iam_credentials_v1; print('ok')"
Ensure Application Default Credentials are available (gcloud auth application-default login or Workload Identity) so the newly installed client can actually mint tokens
If GCP IAM auth was not intended, remove the service_account credential-provider setting to use password auth

Example fix

# before
# requirements.txt
litellm
# -> ImportError at first Redis connect with IAM auth

# after
# requirements.txt
litellm[extra_proxy]

Defensive patterns

Strategy: try-catch

Validate before calling

def gcp_iam_redis_deps_available() -> bool:
    try:
        from google.cloud import iam_credentials_v1  # noqa: F401
        return True
    except ImportError:
        return False


# before enabling IAM auth:
assert gcp_iam_redis_deps_available(), (
    'pip install google-cloud-iam before enabling GCP IAM Redis auth'
)

Try / catch

try:
    litellm.cache = RedisCache(...)  # with GCP IAM credential provider
except ImportError as e:
    if 'google-cloud-iam' in str(e):
        raise SystemExit(
            'Missing google-cloud-iam: install it or disable GCP IAM Redis auth'
        ) from e
    raise

Prevention

Ship the dependency and the config flag in the same change (requirements + settings)
Add an optional-dependency import smoke test to CI for every integration you enable
Check dependencies at container build time, not at first request

When it happens

Trigger: Enabling GCP IAM Redis authentication (a service_account like 'projects/-/serviceAccounts/...@project.iam.gserviceaccount.com' in the Redis credential provider config) on a host where google-cloud-iam is not installed — e.g. base 'pip install litellm' in a slim Docker image.

Common situations: Works on a developer laptop (package present) but fails in CI/production images built from base litellm; enabling IAM token auth in proxy config without updating requirements; namespace-package shadowing from other google-cloud libs breaking the import.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

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/e2cbc4eab6a2d296. Report an issue: GitHub.

Appendix: source

Thrown at litellm/_redis_credential_provider.py:34

# Keyed by service_account → (token, expiry_monotonic_timestamp).
_token_cache: Final[dict[str, tuple[str, float]]] = {}
_token_cache_lock: Final = threading.Lock()


def _generate_gcp_iam_access_token(service_account: str) -> str:
    """
    Generate GCP IAM access token for Redis authentication.

    Args:
        service_account: GCP service account in format 'projects/-/serviceAccounts/name@project.iam.gserviceaccount.com'

    Returns:
        Access token string for GCP IAM authentication
    """
    try:
        from google.cloud import iam_credentials_v1
    except ImportError:
        raise ImportError(
            "google-cloud-iam is required for GCP IAM Redis authentication. "
            "Install it with: pip install google-cloud-iam"
        )

    client: Final = iam_credentials_v1.IAMCredentialsClient()
    request: Final = iam_credentials_v1.GenerateAccessTokenRequest(
        name=service_account,
        scope=["https://www.googleapis.com/auth/cloud-platform"],
    )
    response: Final = client.generate_access_token(request=request)
    return str(response.access_token)


def _get_cached_gcp_iam_token(service_account: str) -> str:
    """
    Return a cached GCP IAM token, refreshing only when expired.

    Uses a module-level cache shared across all GCPIAMCredentialProvider

View on GitHub (pinned to 77b7c6c40c)