{"record":{"id":"fab4ba2d68dfc88e","repo":"apache/iceberg","slug":"cannot-initialize-fileio-implementation-s-s","errorCode":null,"errorMessage":"Cannot initialize FileIO implementation %s: %s","messagePattern":"Cannot initialize FileIO implementation (.+?): (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/CatalogUtil.java","lineNumber":406,"sourceCode":"   * @throws IllegalArgumentException if class path not found or right constructor not found or the\n   *     loaded class cannot be cast to the given interface type\n   */\n  @SuppressWarnings(\"unchecked\")\n  public static FileIO loadFileIO(\n      String impl,\n      Map<String, String> properties,\n      Object hadoopConf,\n      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;","sourceCodeStart":388,"sourceCodeEnd":424,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/CatalogUtil.java#L388-L424","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the fully qualified class name in io-impl (e.g. org.apache.iceberg.aws.s3.S3FileIO, org.apache.iceberg.hadoop.HadoopFileIO).","Add the required connector/bundle JAR to the driver and all executors' classpath.","Ensure the class is public with a public no-arg constructor, or switch to an implementation that has one.","Align Iceberg runtime versions so the configured class name exists in the loaded runtime."],"exampleFix":"// before\nCatalogUtil.loadFileIO(\"org.apache.iceberg.aws.s3a.S3FileIO\", props, conf); // wrong package -> not found\n// after\nCatalogUtil.loadFileIO(\"org.apache.iceberg.aws.s3.S3FileIO\", props, conf);\n// and ensure iceberg-aws-bundle is on the classpath","handlingStrategy":"try-catch","validationCode":"try {\n  Class<?> cls = Class.forName(ioImpl, true, Thread.currentThread().getContextClassLoader());\n  if (!FileIO.class.isAssignableFrom(cls)) {\n    throw new IllegalStateException(ioImpl + \" does not implement FileIO\");\n  }\n} catch (ClassNotFoundException e) {\n  throw new IllegalStateException(\"FileIO class not on classpath: \" + ioImpl, e);\n}","typeGuard":"static boolean isLoadableFileIO(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  LOG.error(\"Cannot load FileIO {} - verify bundle jar (aws/azure/gcp) on driver+executor classpath: {}\", impl, e.getMessage(), e);\n  throw e;\n}","preventionTips":["Deploy the matching cloud bundle JAR (iceberg-aws-bundle etc.) to driver and all executors.","Use standard io-impl class names documented for your Iceberg version.","Smoke-test FileIO loading in CI before production runs.","Keep custom FileIOs public with a public no-arg constructor."],"tags":["reflection","classpath","fileio","initialization"],"backgroundTag":"class-not-found","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"}