apache/iceberg · error · RuntimeIOException

Failed to get file system for path

Error message

Failed to get file system for path: %s

What it means

Util.getFs wraps Path.getFileSystem failures in RuntimeIOException with this message. It obtains a Hadoop FileSystem for a path using the given Configuration; I/O failures resolving or connecting to the file system trigger it.

Solutions

1. Verify the path URI scheme matches a configured FileSystem in the Hadoop Configuration
2. Ensure Hadoop config files are on the classpath and point to the right cluster
3. Check the storage endpoint (Namenode/S3 endpoint) is reachable
4. Confirm required filesystem connector jars (e.g. aws-java-sdk, hdfs client) are present

Example fix

// before
FileSystem fs = Util.getFs(new Path("s3a://bucket/table"), new Configuration());
// after
Configuration conf = new Configuration();
conf.addResource(new Path("/etc/hadoop/conf/core-site.xml"));
FileSystem fs = Util.getFs(new Path("s3a://bucket/table"), conf);

// Ensure the path scheme is supported and Hadoop conf resources are loaded before calling
Configuration conf = new Configuration();
conf.addResource(new Path("/etc/hadoop/conf/core-site.xml"));

try { FileSystem fs = Util.getFs(path, conf); } catch (RuntimeIOException e) { log.error("Cannot resolve FS for {}: {}", path, e.getMessage()); throw e; }

When it happens

Trigger: Calling Util.getFs(path, conf) where the path scheme has no configured FileSystem implementation, or the underlying Hadoop FS client throws IOException (e.g. connection failure to HDFS/Namenode, bad core-site config).

Common situations: Missing Hadoop configuration files (core-site.xml/hdfs-site.xml) on the classpath; wrong URI scheme (e.g. s3a without s3a impl on classpath); NameNode unreachable.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Failed to delete file
• Failed to delete file
• Failed to get status for file
• Failed to list namespace under
• Failed to list tables under

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/hadoop/Util.java:57

import org.apache.iceberg.relocated.com.google.common.collect.Sets;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Util {

  public static final String VERSION_HINT_FILENAME = "version-hint.text";

  private static final Set<String> LOCALITY_WHITELIST_FS = ImmutableSet.of("hdfs");

  private static final Logger LOG = LoggerFactory.getLogger(Util.class);

  private Util() {}

  public static FileSystem getFs(Path path, Configuration conf) {
    try {
      return path.getFileSystem(conf);
    } catch (IOException e) {
      throw new RuntimeIOException(e, "Failed to get file system for path: %s", path);
    }
  }

  public static String[] blockLocations(ScanTaskGroup<FileScanTask> taskGroup, Configuration conf) {
    Set<String> locationSets = Sets.newHashSet();
    for (FileScanTask f : taskGroup.tasks()) {
      Path path = new Path(f.file().location());
      try {
        FileSystem fs = path.getFileSystem(conf);
        for (BlockLocation b : fs.getFileBlockLocations(path, f.start(), f.length())) {
          locationSets.addAll(Arrays.asList(b.getHosts()));
        }
      } catch (IOException ioe) {
        LOG.warn("Failed to get block locations for path {}", path, ioe);
      }
    }

    return locationSets.toArray(new String[0]);

View on GitHub (pinned to 86d9c8fc54)