apache/iceberg · error · UncheckedIOException

Failed to create impersonated credentials for ${impersonateS

Error message

Failed to create impersonated credentials for ${impersonateServiceAccount}

What it means

buildImpersonatedCredentials wraps the IOException from obtaining the source Application Default Credentials (or from the token exchange) into an UncheckedIOException naming the target service account. It is thrown when the base credentials needed to impersonate `impersonateServiceAccount` cannot be loaded or the impersonation flow fails.

Source

Thrown at bigquery/src/main/java/org/apache/iceberg/gcp/bigquery/BigQueryProperties.java:193

  }

  private ImpersonatedCredentials buildImpersonatedCredentials() {
    try {
      GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault();

      ImpersonatedCredentials impersonatedCredentials =
          ImpersonatedCredentials.create(
              sourceCredentials, impersonateServiceAccount, delegates, scopes, lifetimeSeconds);

      // refresh to validate credentials and get initial token
      impersonatedCredentials.refresh();

      LOG.debug(
          "Created impersonated credentials for BigQuery: Target={}", impersonateServiceAccount);

      return impersonatedCredentials;
    } catch (IOException e) {
      throw new UncheckedIOException(
          "Failed to create impersonated credentials for " + impersonateServiceAccount, e);
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

Ensure base ADC is available: `gcloud auth application-default login` or set GOOGLE_APPLICATION_CREDENTIALS to a valid key file.
Verify the impersonated service account exists and the source identity has roles/iam.serviceAccountTokenCreator on it.
Check network reachability to the IAM credentials token endpoint.
Drop impersonation config if base credentials cannot be fixed, and authenticate directly.

Example fix

// before
props.put("gcp.bigquery.impersonate-service-account", "sa@project.iam.gserviceaccount.com"); // no ADC set
// after
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/source-sa.json
props.put("gcp.bigquery.impersonate-service-account", "sa@project.iam.gserviceaccount.com");

Defensive patterns

Strategy: validation

Validate before calling

boolean ready;
try {
  GoogleCredentials.getApplicationDefault();
  ready = true;
} catch (IOException e) {
  ready = false;
}
if (impersonationConfigured && !ready) {
  throw new IllegalStateException("Impersonation requires valid base ADC; configure GOOGLE_APPLICATION_CREDENTIALS first");
}

Try / catch

try {
  metastoreOptions();
} catch (UncheckedIOException e) {
  throw new IllegalStateException("Impersonated credentials failed for target SA: " + e.getCause().getMessage(), e);
}

Prevention

Grant roles/iam.serviceAccountTokenCreator on the target SA to the base identity before enabling impersonation
Verify base ADC works before layering impersonation config on top
Test the token exchange with `gcloud auth print-identity-token` or a small IAM client probe
Keep the impersonated SA email exactly correct (project.iam.gserviceaccount.com)

When it happens

Trigger: metastoreOptions is configured with an impersonation service account but GoogleCredentials.getApplicationDefault() fails (no ADC), or the ImpersonatedCredentials creation fails due to invalid source credentials.

Common situations: Setting the impersonation service-account property without valid base ADC; running off-GCP with no metadata server; the credentials file for the source identity is missing or malformed.

Related errors

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