apache/iceberg · error · IllegalArgumentException

Cannot initialize FileIO implementation %s: %s

Error message

Cannot initialize FileIO implementation %s: %s

What it means

Thrown by CatalogUtil.loadFileIO when the FileIO implementation class name cannot be loaded with a suitable no-arg constructor via DynConstructors — typically because the class is not on the classpath, the name is wrong, or there is no accessible no-arg constructor. The NoSuchMethodException is wrapped as an IllegalArgumentException with the original message and cause.

Source

Thrown at core/src/main/java/org/apache/iceberg/CatalogUtil.java:406

   * @throws IllegalArgumentException if class path not found or right constructor not found or the
   *     loaded class cannot be cast to the given interface type
   */
  @SuppressWarnings("unchecked")
  public static FileIO loadFileIO(
      String impl,
      Map<String, String> properties,
      Object hadoopConf,
      List<StorageCredential> storageCredentials) {
    LOG.info("Loading custom FileIO implementation: {}", impl);
    DynConstructors.Ctor<FileIO> ctor;
    try {
      ctor =
          DynConstructors.builder(FileIO.class)
              .loader(CatalogUtil.class.getClassLoader())
              .impl(impl)
              .buildChecked();
    } catch (NoSuchMethodException e) {
      throw new IllegalArgumentException(
          String.format("Cannot initialize FileIO implementation %s: %s", impl, e.getMessage()), e);
    }

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

    configureHadoopConf(fileIO, hadoopConf);
    if (fileIO instanceof SupportsStorageCredentials) {
      ((SupportsStorageCredentials) fileIO).setCredentials(storageCredentials);
    }

    fileIO.initialize(properties);
    return fileIO;

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the fully qualified class name in io-impl (e.g. org.apache.iceberg.aws.s3.S3FileIO, org.apache.iceberg.hadoop.HadoopFileIO).
2. Add the required connector/bundle JAR to the driver and all executors' classpath.
3. Ensure the class is public with a public no-arg constructor, or switch to an implementation that has one.
4. Align Iceberg runtime versions so the configured class name exists in the loaded runtime.

Example fix

// before
CatalogUtil.loadFileIO("org.apache.iceberg.aws.s3a.S3FileIO", props, conf); // wrong package -> not found
// after
CatalogUtil.loadFileIO("org.apache.iceberg.aws.s3.S3FileIO", props, conf);
// and ensure iceberg-aws-bundle is on the classpath

try {
  Class<?> cls = Class.forName(ioImpl, true, Thread.currentThread().getContextClassLoader());
  if (!FileIO.class.isAssignableFrom(cls)) {
    throw new IllegalStateException(ioImpl + " does not implement FileIO");
  }
} catch (ClassNotFoundException e) {
  throw new IllegalStateException("FileIO class not on classpath: " + ioImpl, e);
}

static boolean isLoadableFileIO(String impl) {
  try {
    return FileIO.class.isAssignableFrom(Class.forName(impl));
  } catch (Throwable t) {
    return false;
  }
}

try {
  FileIO io = CatalogUtil.loadFileIO(impl, props, conf);
} catch (IllegalArgumentException e) {
  LOG.error("Cannot load FileIO {} - verify bundle jar (aws/azure/gcp) on driver+executor classpath: {}", impl, e.getMessage(), e);
  throw e;
}

When it happens

Trigger: Calling CatalogUtil.loadFileIO(impl, properties, hadoopConf) (directly or via io-impl configuration on a table/catalog) with a class name that is absent from the classpath or lacks a public no-arg constructor.

Common situations: Missing bundle JAR (iceberg-aws-bundle/azure-bundle/gcp-bundle) on Spark/Flink executors; typo in io-impl such as org.apache.iceberg.aws.s3.S3fileIO; running with HadoopFileIO expected but class renamed/moved between Iceberg versions; shaded classpath relocating the FileIO interface so the lookup fails.

Related errors

• Cannot initialize Catalog implementation %s: %s
• Cannot load class %s, it does not exist in the classpath
• Cannot load class %s, it does not exist in the classpath
• Cannot find class; alternatives: ${classNames}
• Cannot find method: ${name}

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