apache/iceberg · error · IllegalArgumentException

Cannot initialize FileIO, %s does not implement FileIO.

Error message

Cannot initialize FileIO, %s does not implement FileIO.

What it means

Thrown by CatalogUtil.loadFileIO when the configured class instantiates successfully but does not implement org.apache.iceberg.FileIO; ctor.newInstance() then throws ClassCastException, which is translated into this IllegalArgumentException with the original cause preserved.

Source

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

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

  /**
   * Dynamically detects whether an object is a Hadoop Configurable and calls setConf.
   *
   * @param maybeConfigurable an object that may be Configurable
   * @param conf a Configuration
   */

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Set io-impl to a class implementing org.apache.iceberg.FileIO (e.g. org.apache.iceberg.aws.s3.S3FileIO, org.apache.iceberg.hadoop.HadoopFileIO).
2. Move any Catalog implementation class name from io-impl to catalog-impl / type configuration.
3. Remove duplicate Iceberg JARs so a single FileIO interface is visible to all classloaders.
4. Rebuild custom FileIO implementations against the Iceberg version in use.

Example fix

// before
CatalogUtil.loadFileIO("org.apache.iceberg.rest.RESTCatalog", props, conf); // Catalog, not FileIO
// after
CatalogUtil.loadFileIO("org.apache.iceberg.aws.s3.S3FileIO", props, conf);

Class<?> cls = Class.forName(ioImpl);
if (!FileIO.class.isAssignableFrom(cls)) {
  throw new IllegalArgumentException(ioImpl + " does not implement org.apache.iceberg.FileIO");
}

static boolean implementsIcebergFileIO(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) {
  if (e.getCause() instanceof ClassCastException) {
    throw new ConfigException("io-impl %s is not a FileIO implementation", impl, e);
  }
  throw e;
}

When it happens

Trigger: Passing a class name to loadFileIO (or via io-impl) that resolves to a non-FileIO class — e.g. a Catalog implementation, an arbitrary helper class with a no-arg constructor, or a class implementing a relocated FileIO interface from a different Iceberg version/classloader.

Common situations: Putting a catalog class into io-impl instead of catalog-impl; classpath containing two Iceberg versions so the loaded class implements a different FileIO interface; custom IO written against a stale interface; copy-paste of impl names between configuration keys.

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 Catalog, %s does not implement Catalog.
• Cannot initialize AliyunClientFactory, %s does not implement
• Cannot initialize AwsClientFactory, %s does not implement Aw
• Cannot initialize AdlsTokenCredentialProvider, %s does not i
• Cannot initialize FileIO implementation %s: %s

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