{"record":{"id":"e2cbc4eab6a2d296","repo":"BerriAI/litellm","slug":"google-cloud-iam-is-required-for-gcp-iam-redis-aut","errorCode":null,"errorMessage":"google-cloud-iam is required for GCP IAM Redis authentication. Install it with: pip install google-cloud-iam","messagePattern":"google-cloud-iam is required for GCP IAM Redis authentication\\. Install it with: pip install google-cloud-iam","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"litellm/_redis_credential_provider.py","lineNumber":34,"sourceCode":"# Keyed by service_account → (token, expiry_monotonic_timestamp).\n_token_cache: Final[dict[str, tuple[str, float]]] = {}\n_token_cache_lock: Final = threading.Lock()\n\n\ndef _generate_gcp_iam_access_token(service_account: str) -> str:\n    \"\"\"\n    Generate GCP IAM access token for Redis authentication.\n\n    Args:\n        service_account: GCP service account in format 'projects/-/serviceAccounts/name@project.iam.gserviceaccount.com'\n\n    Returns:\n        Access token string for GCP IAM authentication\n    \"\"\"\n    try:\n        from google.cloud import iam_credentials_v1\n    except ImportError:\n        raise ImportError(\n            \"google-cloud-iam is required for GCP IAM Redis authentication. \"\n            \"Install it with: pip install google-cloud-iam\"\n        )\n\n    client: Final = iam_credentials_v1.IAMCredentialsClient()\n    request: Final = iam_credentials_v1.GenerateAccessTokenRequest(\n        name=service_account,\n        scope=[\"https://www.googleapis.com/auth/cloud-platform\"],\n    )\n    response: Final = client.generate_access_token(request=request)\n    return str(response.access_token)\n\n\ndef _get_cached_gcp_iam_token(service_account: str) -> str:\n    \"\"\"\n    Return a cached GCP IAM token, refreshing only when expired.\n\n    Uses a module-level cache shared across all GCPIAMCredentialProvider","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/_redis_credential_provider.py#L16-L52","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\n# requirements.txt\nlitellm\n# -> ImportError at first Redis connect with IAM auth\n\n# after\n# requirements.txt\nlitellm[extra_proxy]","handlingStrategy":"try-catch","validationCode":"def gcp_iam_redis_deps_available() -> bool:\n    try:\n        from google.cloud import iam_credentials_v1  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\n\n# before enabling IAM auth:\nassert gcp_iam_redis_deps_available(), (\n    'pip install google-cloud-iam before enabling GCP IAM Redis auth'\n)","typeGuard":null,"tryCatchPattern":"try:\n    litellm.cache = RedisCache(...)  # with GCP IAM credential provider\nexcept ImportError as e:\n    if 'google-cloud-iam' in str(e):\n        raise SystemExit(\n            'Missing google-cloud-iam: install it or disable GCP IAM Redis auth'\n        ) from e\n    raise","preventionTips":["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"],"tags":["redis","gcp","iam","dependency","import-error"],"backgroundTag":"missing-optional-dependency","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}