apache/iceberg · error · IllegalArgumentException

Cannot initialize AwsClientFactory

Error message

Cannot initialize AwsClientFactory, %s does not implement AwsClientFactory.

What it means

After reflectively instantiating the class named by the client.factory-impl property, AwsClientFactories casts the new instance to AwsClientFactory. This error is thrown when the cast fails (ClassCastException), meaning the configured class exists and has a no-arg constructor but does not implement the AwsClientFactory interface. The IllegalArgumentException wraps the ClassCastException.

Solutions

1. Make the configured class implement org.apache.iceberg.aws.AwsClientFactory (the exact interface from the Iceberg version in use).
2. Check for duplicate/conflicting versions of iceberg-aws-bundle on the classpath that define a different AwsClientFactory; align versions.
3. Verify the fully-qualified class name in client.factory-impl is correct and matches the compiled implementation.

Example fix

// before
public class MyFactory implements com.other.AwsClientFactory { ... }
// after
import org.apache.iceberg.aws.AwsClientFactory;
public class MyFactory implements AwsClientFactory {
  public s3.FileIO newS3FileIO() { ... }
  public void initialize(Map<String, String> properties) { ... }
}

Class<?> c = Class.forName(props.get("client.factory-impl"));
if (!org.apache.iceberg.aws.AwsClientFactory.class.isAssignableFrom(c)) {
  throw new IllegalStateException(c.getName() + " does not implement org.apache.iceberg.aws.AwsClientFactory");
}

function implementsAwsClientFactory(Class<?> c) {
  return org.apache.iceberg.aws.AwsClientFactory.class.isAssignableFrom(c);
}

try {
  factory = AwsClientFactories.from(props);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("does not implement AwsClientFactory")) {
    throw new IllegalStateException("Check classpath for duplicate iceberg-aws versions and confirm the impl class implements AwsClientFactory", e);
  }
  throw e;
}

When it happens

Trigger: Setting client.factory-impl to a class that implements a different (or stale/older-packaged) AwsClientFactory interface, or to a completely unrelated class with a no-arg constructor, e.g. a wrong class name typo that happens to resolve to another type on the classpath.

Common situations: Classpath containing two versions of the interface (shaded vs unshaded packages) so the implementation implements a different interface than the one DynConstructors resolves; copying a factory from another project with a different interface; typo pointing to a random no-arg class.

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 create to generate and configure the client SDK…
• Cannot initialize AwsClientFactory, missing no-arg…
• Cannot assume role to sign REST requests because is not…
• Cannot create an instance of
• Cannot create an instance of

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

Appendix: source

Thrown at aws/src/main/java/org/apache/iceberg/aws/AwsClientFactories.java:84

  private static AwsClientFactory loadClientFactory(String impl, Map<String, String> properties) {
    DynConstructors.Ctor<AwsClientFactory> ctor;
    try {
      ctor =
          DynConstructors.builder(AwsClientFactory.class)
              .loader(AwsClientFactories.class.getClassLoader())
              .hiddenImpl(impl)
              .buildChecked();
    } catch (NoSuchMethodException e) {
      throw new IllegalArgumentException(
          String.format("Cannot initialize AwsClientFactory, missing no-arg constructor: %s", impl),
          e);
    }

    AwsClientFactory factory;
    try {
      factory = ctor.newInstance();
    } catch (ClassCastException e) {
      throw new IllegalArgumentException(
          String.format(
              "Cannot initialize AwsClientFactory, %s does not implement AwsClientFactory.", impl),
          e);
    }

    factory.initialize(properties);
    return factory;
  }

  static class DefaultAwsClientFactory implements AwsClientFactory {
    private AwsProperties awsProperties;
    private AwsClientProperties awsClientProperties;
    private S3FileIOProperties s3FileIOProperties;
    private HttpClientProperties httpClientProperties;

    DefaultAwsClientFactory() {
      awsProperties = new AwsProperties();
      awsClientProperties = new AwsClientProperties();

View on GitHub (pinned to 86d9c8fc54)