apache/iceberg · error · IllegalArgumentException

Cannot initialize AwsClientFactory, %s does not implement Aw

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.

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)

Solutions

Make the configured class implement org.apache.iceberg.aws.AwsClientFactory (the exact interface from the Iceberg version in use).
Check for duplicate/conflicting versions of iceberg-aws-bundle on the classpath that define a different AwsClientFactory; align versions.
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) { ... }
}

Defensive patterns

Strategy: validation

Validate before calling

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");
}

Type guard

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

Try / catch

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;
}

Prevention

Implement the exact org.apache.iceberg.aws.AwsClientFactory interface matching your Iceberg version.
Keep a single version of iceberg-aws-bundle on the classpath to avoid interface identity conflicts.
Add an integration test that loads the factory via AwsClientFactories.from at startup.

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

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