apache/iceberg · error · UncheckedIOException

Failed to create impersonated credentials for GCS

Error message

Failed to create impersonated credentials for GCS

What it means

PrefixedStorage.buildImpersonatedCredentials() wraps IOException from creating or refreshing Google impersonated credentials into UncheckedIOException. It means the service-account impersonation flow for GCS access could not be set up or its initial token fetched.

Solutions

1. Verify the impersonated service-account email and that the caller has serviceAccountTokenCreator IAM role
2. Check the configured credential source (key file / ADC) is valid: gcloud auth application-default login
3. Test network reachability to the OAuth2 token endpoint (oauth2.googleapis.com)
4. Review gcs.* impersonation properties (target principal, lifetime, delegation tokens) for typos

Example fix

// before
Catalog catalog = CatalogLoader.load(...); // with wrong gcs.impersonation target
// after
conf.set("io.iceberg.gcs.impersonate-service-account", "correct-sa@project.iam.gserviceaccount.com");

// pre-check: GoogleCredentials source loads and IAM tokenCreator role exists
// gcloud storage ls gs://bucket && gcloud iam service-accounts describe SA_EMAIL

try { storage = new PrefixedStorage(...).credentials(); } catch (UncheckedIOException e) { throw new IllegalStateException("Impersonation setup failed: " + e.getCause(), e); }

When it happens

Trigger: Configuring gcs.project-id / impersonation properties (impersonated service account, delegation token, lifetime) and the underlying Google credentials.refresh() fails — bad key file, missing IAM permissions, or network failure to the token endpoint.

Common situations: Wrong service account email in impersonation config; caller lacking roles/iam.serviceAccountTokenCreator; unreachable OAuth2 token endpoint (proxy/firewall); invalid or unreadable credential key file.

Related errors

• Cannot specify both and
• Failed to create impersonated credentials for
• Failed to get application default credentials
• Failed to load Google credentials
• Failed to obtain Google access token. Cannot authenticate…

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/d1b8c5c1e1862afa. Report an issue: GitHub.

Appendix: source

Thrown at gcp/src/main/java/org/apache/iceberg/gcp/gcs/PrefixedStorage.java:182

  }

  private Credentials buildImpersonatedCredentials(GCPProperties properties) {
    try {
      GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault();

      ImpersonatedCredentials impersonatedCredentials =
          ImpersonatedCredentials.create(
              sourceCredentials,
              properties.impersonateServiceAccount().get(),
              properties.impersonateDelegates(),
              properties.impersonateScopes(),
              properties.impersonateLifetimeSeconds());

      // Refresh to get initial token
      impersonatedCredentials.refresh();
      return impersonatedCredentials;
    } catch (IOException e) {
      throw new UncheckedIOException("Failed to create impersonated credentials for GCS", e);
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)