{"record":{"id":"16571b45cd1a71c9","repo":"apache/iceberg","slug":"failed-to-create-gcp-cloud-kms-service-client","errorCode":null,"errorMessage":"Failed to create GCP cloud KMS service client","messagePattern":"Failed to create GCP cloud KMS service client","errorType":"exception","errorClass":"RuntimeIOException","httpStatus":null,"severity":"error","filePath":"gcp/src/main/java/org/apache/iceberg/gcp/GcpKeyManagementClient.java","lineNumber":123,"sourceCode":"    if (kmsClient == null) {\n      synchronized (this) {\n        if (kmsClient == null) {\n          GCPProperties gcpProperties = new GCPProperties(allProperties);\n          try {\n            KeyManagementServiceSettings.Builder kmsBuilder =\n                KeyManagementServiceSettings.newBuilder();\n            if (gcpProperties.oauth2Token().isPresent()) {\n              OAuth2Credentials oAuth2Credentials =\n                  GCPAuthUtils.oauth2CredentialsFromGcpProperties(gcpProperties, closeableGroup);\n              kmsBuilder.setCredentialsProvider(FixedCredentialsProvider.create(oAuth2Credentials));\n            }\n\n            // if not OAuth then defaults to GoogleCredentials.getApplicationDefault()\n            this.kmsClient = KeyManagementServiceClient.create(kmsBuilder.build());\n            closeableGroup.addCloseable(kmsClient);\n\n          } catch (IOException e) {\n            throw new RuntimeIOException(e, \"Failed to create GCP cloud KMS service client\");\n          }\n        }\n      }\n    }\n    return kmsClient;\n  }\n\n  private static final class ByteStringShim {\n    private static final String ORIGINAL_BYTE_STRING_CLASS_NAME = \"com.google.protobuf.ByteString\";\n    private static final String SHADED_BYTE_STRING_CLASS_NAME =\n        \"org.apache.iceberg.gcp.shaded.\" + ORIGINAL_BYTE_STRING_CLASS_NAME;\n    private static final Class<?> BYTE_STRING_CLASS;\n\n    static {\n      Class<?> byteStringClass =\n          DynClasses.builder().impl(SHADED_BYTE_STRING_CLASS_NAME).orNull().build();\n      if (byteStringClass == null) {\n        byteStringClass = DynClasses.builder().impl(ORIGINAL_BYTE_STRING_CLASS_NAME).build();","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/gcp/src/main/java/org/apache/iceberg/gcp/GcpKeyManagementClient.java#L105-L141","documentation":"GcpKeyManagementClient lazily creates a Google Cloud KeyManagementServiceClient. If client construction throws IOException (credential resolution, endpoint reachability, environment problems), it is wrapped in RuntimeIOException('Failed to create GCP cloud KMS service client').","triggerScenarios":"First call to kmsClient() when KeyManagementServiceClient.create fails — typically Application Default Credentials are unavailable, the credentials file is missing/invalid, or the GCP KMS endpoint cannot be reached.","commonSituations":"Missing GOOGLE_APPLICATION_CREDENTIALS env var, workload identity not configured on the compute environment, private network without access to googleapis.com, or malformed gcp credentials JSON.","solutions":["Verify credentials are resolvable: GOOGLE_APPLICATION_CREDENTIALS set to a valid service-account JSON or ADC configured via gcloud auth application-default login","Confirm workload identity / service account attachment on GKE/Cloud Run/Compute","Check network egress to cloudkms.googleapis.com (proxies, VPC-SC, private Google access)","Validate the credentials file JSON and scopes before startup"],"exampleFix":"// before\n// no credential setup; client created lazily and fails at first use\n// after\n// fail fast at startup\nGoogleAuthManager auth = ...; auth.initialize(properties); // validates credentials early\nKmsClient client = new GcpKeyManagementClient(properties).kmsClient();","handlingStrategy":"try-catch","validationCode":"// pre-flight: can ADC resolve credentials?\ntry { GoogleCredentials.getApplicationDefault().createScoped(\"https://www.googleapis.com/auth/cloud-platform\"); } catch (IOException e) { throw new IllegalStateException(\"No GCP credentials configured\", e); }","typeGuard":null,"tryCatchPattern":"try { client.kmsClient(); } catch (RuntimeIOException e) { LOG.error(\"KMS client init failed — check GCP credentials/network\", e); throw e; }","preventionTips":["Initialize/auth early at startup, not lazily at first use","Set GOOGLE_APPLICATION_CREDENTIALS or use workload identity","Verify egress to cloudkms.googleapis.com in restricted networks"],"tags":["gcp","kms","io","credentials","client-init"],"backgroundTag":"module-init-failed","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}