apache/iceberg · error · IllegalArgumentException

Cannot initialize kms client, ${kmsImpl} does not implement

Error message

Cannot initialize kms client, ${kmsImpl} does not implement KeyManagementClient interface

What it means

Thrown by EncryptionUtil.createKmsClient when the class named by the kmsImpl configuration property was instantiated reflectively but does not implement the KeyManagementClient interface. The library requires every custom KMS client to implement this interface so it can be used uniformly for key wrapping/unwrapping. The original ClassCastException is chained as the cause.

Source

Thrown at core/src/main/java/org/apache/iceberg/encryption/EncryptionUtil.java:89

    DynConstructors.Ctor<KeyManagementClient> ctor;
    try {
      ctor =
          DynConstructors.builder(KeyManagementClient.class)
              .loader(EncryptionUtil.class.getClassLoader())
              .impl(kmsImpl)
              .buildChecked();
    } catch (NoSuchMethodException e) {
      throw new IllegalArgumentException(
          String.format(
              "Cannot initialize KeyManagementClient, missing no-arg constructor for class %s",
              kmsImpl),
          e);
    }

    try {
      kmsClient = ctor.newInstance();
    } catch (ClassCastException e) {
      throw new IllegalArgumentException(
          String.format(
              "Cannot initialize kms client, %s does not implement KeyManagementClient interface",
              kmsImpl),
          e);
    }

    kmsClient.initialize(catalogProperties);

    return kmsClient;
  }

  public static EncryptionManager createEncryptionManager(
      List<EncryptedKey> keys, Map<String, String> tableProperties, KeyManagementClient kmsClient) {
    Preconditions.checkArgument(kmsClient != null, "Invalid KMS client: null");
    String tableKeyId = tableProperties.get(TableProperties.ENCRYPTION_TABLE_KEY);

    if (null == tableKeyId) {
      // Unencrypted table

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Make the configured class implement org.apache.iceberg.encryption.KeyManagementClient (or extend a base adapter that does)
2. Verify the kms-impl property value points to the intended client class, not a wrapper or helper
3. Check the Iceberg version's docs: older samples may reference classes that predate KeyManagementClient

Example fix

// before
public class MyKmsClient implements KmsClient { ... }
// after
public class MyKmsClient implements KeyManagementClient { ... }

Class<?> clazz = Class.forName(kmsImpl);
if (!KeyManagementClient.class.isAssignableFrom(clazz)) {
  throw new IllegalArgumentException(kmsImpl + " must implement KeyManagementClient");
}

boolean isKmsClient(Object o) { return o instanceof KeyManagementClient; }

try { kmsClient = EncryptionUtil.createKmsClient(kmsImpl); }
catch (IllegalArgumentException e) { log.error("Bad kms-impl: {}", kmsImpl, e); throw e; }

When it happens

Trigger: Calling EncryptionUtil.createKmsClient (directly or via table encryption configuration) with a kms-impl property pointing to a class that exists and has a no-arg constructor but only implements KmsClient, not KeyManagementClient.

Common situations: Configuring an old custom KMS client class written against a previous interface; pointing kms-impl at a helper/wrapper class instead of the actual client; copy-pasting an impl class name from documentation for a different Iceberg version.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Cannot initialize KeyManagementClient, missing no-arg constr
• Unsupported KMS type: ${kmsType}
• Cannot initialize AliyunClientFactory, missing no-arg constr
• Key generation is not supported in this KmsClient
• Cannot initialize AwsClientFactory, missing no-arg construct

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