{"record":{"id":"898fb16445cf1bff","repo":"apache/iceberg","slug":"cannot-initialize-fileio-s-does-not-implement-fi","errorCode":null,"errorMessage":"Cannot initialize FileIO, %s does not implement FileIO.","messagePattern":"Cannot initialize FileIO, (.+?) does not implement FileIO\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/CatalogUtil.java","lineNumber":414,"sourceCode":"      List<StorageCredential> storageCredentials) {\n    LOG.info(\"Loading custom FileIO implementation: {}\", impl);\n    DynConstructors.Ctor<FileIO> ctor;\n    try {\n      ctor =\n          DynConstructors.builder(FileIO.class)\n              .loader(CatalogUtil.class.getClassLoader())\n              .impl(impl)\n              .buildChecked();\n    } catch (NoSuchMethodException e) {\n      throw new IllegalArgumentException(\n          String.format(\"Cannot initialize FileIO implementation %s: %s\", impl, e.getMessage()), e);\n    }\n\n    FileIO fileIO;\n    try {\n      fileIO = ctor.newInstance();\n    } catch (ClassCastException e) {\n      throw new IllegalArgumentException(\n          String.format(\"Cannot initialize FileIO, %s does not implement FileIO.\", impl), e);\n    }\n\n    configureHadoopConf(fileIO, hadoopConf);\n    if (fileIO instanceof SupportsStorageCredentials) {\n      ((SupportsStorageCredentials) fileIO).setCredentials(storageCredentials);\n    }\n\n    fileIO.initialize(properties);\n    return fileIO;\n  }\n\n  /**\n   * Dynamically detects whether an object is a Hadoop Configurable and calls setConf.\n   *\n   * @param maybeConfigurable an object that may be Configurable\n   * @param conf a Configuration\n   */","sourceCodeStart":396,"sourceCodeEnd":432,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/CatalogUtil.java#L396-L432","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set io-impl to a class implementing org.apache.iceberg.FileIO (e.g. org.apache.iceberg.aws.s3.S3FileIO, org.apache.iceberg.hadoop.HadoopFileIO).","Move any Catalog implementation class name from io-impl to catalog-impl / type configuration.","Remove duplicate Iceberg JARs so a single FileIO interface is visible to all classloaders.","Rebuild custom FileIO implementations against the Iceberg version in use."],"exampleFix":"// before\nCatalogUtil.loadFileIO(\"org.apache.iceberg.rest.RESTCatalog\", props, conf); // Catalog, not FileIO\n// after\nCatalogUtil.loadFileIO(\"org.apache.iceberg.aws.s3.S3FileIO\", props, conf);","handlingStrategy":"validation","validationCode":"Class<?> cls = Class.forName(ioImpl);\nif (!FileIO.class.isAssignableFrom(cls)) {\n  throw new IllegalArgumentException(ioImpl + \" does not implement org.apache.iceberg.FileIO\");\n}","typeGuard":"static boolean implementsIcebergFileIO(String impl) {\n  try {\n    return FileIO.class.isAssignableFrom(Class.forName(impl));\n  } catch (Throwable t) {\n    return false;\n  }\n}","tryCatchPattern":"try {\n  FileIO io = CatalogUtil.loadFileIO(impl, props, conf);\n} catch (IllegalArgumentException e) {\n  if (e.getCause() instanceof ClassCastException) {\n    throw new ConfigException(\"io-impl %s is not a FileIO implementation\", impl, e);\n  }\n  throw e;\n}","preventionTips":["Never place Catalog implementation classes under io-impl (and vice versa).","Ensure only one Iceberg version is on the classpath to avoid FileIO interface split across classloaders.","Compile custom FileIOs against the exact Iceberg runtime version deployed.","List the intended impl classes in a constants/config-allowlist and validate at startup."],"tags":["reflection","classcast","fileio","type-mismatch"],"backgroundTag":"type-mismatch","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"}