{"record":{"id":"5afe198d5d5898aa","repo":"apache/iceberg","slug":"class-s-not-found-s","errorCode":null,"errorMessage":"Class %s not found : %s","messagePattern":"Class (.+?) not found : (.+?)","errorType":"exception","errorClass":"ValidationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/io/ResolvingFileIO.java","lineNumber":244,"sourceCode":"          Preconditions.checkState(\n              fileIO instanceof DelegateFileIO,\n              \"FileIO does not implement DelegateFileIO: \" + fileIO.getClass().getName());\n\n          return (DelegateFileIO) fileIO;\n        });\n  }\n\n  @VisibleForTesting\n  String implFromLocation(String location) {\n    return SCHEME_TO_FILE_IO.getOrDefault(scheme(location), FALLBACK_IMPL);\n  }\n\n  public Class<?> ioClass(String location) {\n    String fileIOClassName = implFromLocation(location);\n    try {\n      return Class.forName(fileIOClassName);\n    } catch (ClassNotFoundException e) {\n      throw new ValidationException(\"Class %s not found : %s\", fileIOClassName, e.getMessage());\n    }\n  }\n\n  private static String scheme(String location) {\n    int colonPos = location.indexOf(\":\");\n    if (colonPos > 0) {\n      return location.substring(0, colonPos);\n    }\n\n    return null;\n  }\n\n  @SuppressWarnings({\"checkstyle:NoFinalizer\", \"Finalize\", \"deprecation\"})\n  @Override\n  protected void finalize() throws Throwable {\n    super.finalize();\n    if (!isClosed.get()) {\n      close();","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/io/ResolvingFileIO.java#L226-L262","documentation":"ResolvingFileIO maps a location's scheme to a FileIO implementation class name via implFromLocation, then loads it reflectively with Class.forName. ValidationException is thrown when that class name cannot be found on the classpath, typically because the corresponding FileIO module (e.g. Hadoop) is not a dependency.","triggerScenarios":"Calling ResolvingFileIO.ioClass(location) (directly or indirectly via usesHadoopFileIO) with a location whose mapped FileIO class is missing from the runtime classpath, e.g. an s3/hdfs/abfs location without the matching FileIO module loaded.","commonSituations":"Deploying a Spark/Flink job without the iceberg-aws or iceberg-hadoop-mr shaded jar; shading that excludes FileIO implementations; typos in custom FileIO class names in configuration; a location scheme (e.g. gcs) with no registered implementation.","solutions":["Add the shaded FileIO runtime jar for the location's scheme (iceberg-aws-bundle, iceberg-azure-bundle, iceberg-gcp-bundle, or iceberg-hadoop-mr) to the classpath.","Verify the fully-qualified class name of any custom FileIO configured for the scheme is correct and present in the deployed artifact.","Run the job with a fat/shaded jar that does not exclude io.* classes from relocation.","Check that the scheme prefix in the location is spelled correctly so the expected implementation is resolved."],"exampleFix":"// before\nspark-submit --packages org.apache.iceberg:iceberg-spark-runtime-4.1_2.13:... \\\n  job.jar  // s3:// paths fail: no S3FileIO on classpath\n\n// after\nspark-submit --packages org.apache.iceberg:iceberg-spark-runtime-4.1_2.13:...,org.apache.iceberg:iceberg-aws-bundle:... \\\n  job.jar","handlingStrategy":"validation","validationCode":"String cls = ioProps.getOrDefault(scheme(location) + \".impl\", defaultFor(scheme(location)));\ntry {\n  Class.forName(cls);\n} catch (ClassNotFoundException e) {\n  throw new IllegalStateException(\"FileIO class missing from classpath: \" + cls +\n      \". Add the matching iceberg-*-bundle jar.\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n  catalog.initialize(\"app\", props);\n} catch (ValidationException e) {\n  if (e.getMessage().contains(\"not found\")) {\n    log.error(\"FileIO implementation missing: add iceberg-aws-bundle/iceberg-hadoop-mr to classpath\");\n  }\n  throw e;\n}","preventionTips":["Ship shaded runtime bundles (iceberg-aws-bundle, iceberg-azure-bundle, iceberg-gcp-bundle) for every scheme you read","Add a startup smoke test that opens a file via ResolvingFileIO for each configured scheme","Never rely on compile-scope deps for FileIO implementations in distributed jobs — use runtime/bundle jars"],"tags":["classpath","fileio","reflective-load"],"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-23T08:17:48.524Z"}