{"record":{"id":"595a5ab449a616c3","repo":"apache/iceberg","slug":"cannot-initialize-s3fileioawsclientfactory-s-doe","errorCode":null,"errorMessage":"Cannot initialize S3FileIOAwsClientFactory, %s does not implement S3FileIOAwsClientFactory.","messagePattern":"Cannot initialize S3FileIOAwsClientFactory, (.+?) does not implement S3FileIOAwsClientFactory\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aws/src/main/java/org/apache/iceberg/aws/S3FileIOAwsClientFactories.java","lineNumber":70,"sourceCode":"    DynConstructors.Ctor<S3FileIOAwsClientFactory> ctor;\n    try {\n      ctor =\n          DynConstructors.builder(S3FileIOAwsClientFactory.class)\n              .loader(S3FileIOAwsClientFactories.class.getClassLoader())\n              .hiddenImpl(impl)\n              .buildChecked();\n    } catch (NoSuchMethodException e) {\n      throw new IllegalArgumentException(\n          String.format(\n              \"Cannot initialize S3FileIOAwsClientFactory, missing no-arg constructor: %s\", impl),\n          e);\n    }\n\n    S3FileIOAwsClientFactory factory;\n    try {\n      factory = ctor.newInstance();\n    } catch (ClassCastException e) {\n      throw new IllegalArgumentException(\n          String.format(\n              \"Cannot initialize S3FileIOAwsClientFactory, %s does not implement S3FileIOAwsClientFactory.\",\n              impl),\n          e);\n    }\n\n    factory.initialize(properties);\n    return factory;\n  }\n}\n","sourceCodeStart":52,"sourceCodeEnd":81,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/aws/src/main/java/org/apache/iceberg/aws/S3FileIOAwsClientFactories.java#L52-L81","documentation":"S3FileIOawsClientFactories.load() loads a user-configured factory class (via the `s3.io-aws.client-factory-impl` property) and reflectively instantiates it. After construction the result is cast to S3FileIOAwsClientFactory; if the configured class does not implement that interface, the ClassCastException is rethrown as this IllegalArgumentException. This guards the S3FileIO against custom client factories of the wrong type.","triggerScenarios":"Calling S3FileIO.initialize() when the property `s3.io-aws.client-factory-impl` (ClientFactory.IMPLEMENTATION) points to a class that instantiates successfully but does not implement the S3FileIOAwsClientFactory interface, causing ctor.newInstance() + implicit cast to throw ClassCastException.","commonSituations":"Typo pointing at a ClientFactory built for a different IO (e.g. a Glue or DynamoDb client factory class); implementing the wrong interface after an SDK refactor; a class implementing an older/renamed interface from a different Iceberg version; passing the factory's class name instead of an implementing class.","solutions":["Make the configured class implement org.apache.iceberg.aws.S3FileIOAwsClientFactory (and its initialize(Map) method).","Check the `s3.io-aws.client-factory-impl` property value for typos or pointing at the wrong class (e.g. a DynamoDbFileIOAwsClientFactory).","Verify the Iceberg AWS dependency version used to compile the custom factory matches the runtime version, since the interface may have changed."],"exampleFix":"// before\nprops.put(\"s3.io-aws.client-factory-impl\", \"com.example.MyCustomFactory\"); // MyCustomFactory implements AwsClientFactory\nclass MyCustomFactory implements AwsClientFactory { ... }\n\n// after\nclass MyCustomFactory implements S3FileIOAwsClientFactory {\n  @Override\n  public void initialize(Map<String, String> properties) { ... }\n  ...\n}","handlingStrategy":"try-catch","validationCode":"Class<?> cls = Class.forName(factoryImpl);\nif (!S3FileIOAwsClientFactory.class.isAssignableFrom(cls)) {\n  throw new IllegalStateException(factoryImpl + \" must implement S3FileIOAwsClientFactory\");\n}","typeGuard":"if (instance instanceof S3FileIOAwsClientFactory factory) { use(factory); }","tryCatchPattern":"try {\n  io.initialize(props);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"does not implement S3FileIOAwsClientFactory\")) {\n    log.error(\"Check s3.io-aws.client-factory-impl: {}\", props.get(\"s3.io-aws.client-factory-impl\"), e);\n  }\n  throw e;\n}","preventionTips":["Confirm the class implements S3FileIOAwsClientFactory, not another client-factory interface","Pin the Iceberg AWS dependency version used to compile custom factories to the runtime version","Add a startup smoke test that instantiates the configured factory before workloads run"],"tags":["aws","s3","configuration","class-cast"],"backgroundTag":"incompatible-source-type","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"}