What causes "Failed to open file: %s" in apache/iceberg?

Verify the file exists and is readable at the reported location (check FileIO, credentials, filesystem config)

apache/iceberg · error · RuntimeIOException

Failed to open file: %s

Error message

Failed to open file: %s

What it means

ORC.read(file) opens an ORC file via OrcFile.createReader with the configured reader options. If an IOException occurs during open (missing file, corrupt footer, filesystem/network errors), it is rethrown as RuntimeIOException with 'Failed to open file: <location>'.

Source

Thrown at orc/src/main/java/org/apache/iceberg/orc/ORC.java:808

          batchedReaderFunc,
          recordsPerBatch);
    }
  }

  static Reader newFileReader(InputFile file, Configuration config) {
    ReaderOptions readerOptions = OrcFile.readerOptions(config).useUTCTimestamp(true);
    if (file instanceof HadoopInputFile) {
      readerOptions.filesystem(((HadoopInputFile) file).getFileSystem());
    } else {
      // In case of any other InputFile we wrap the InputFile with InputFileSystem that only
      // supports the creation of an InputStream. To prevent a file status call to determine the
      // length we supply the length as input
      readerOptions.filesystem(new FileIOFSUtil.InputFileSystem(file)).maxLength(file.getLength());
    }
    try {
      return OrcFile.createReader(new Path(file.location()), readerOptions);
    } catch (IOException ioe) {
      throw new RuntimeIOException(ioe, "Failed to open file: %s", file.location());
    }
  }

  static Writer newFileWriter(
      OutputFile file, OrcFile.WriterOptions options, Map<String, byte[]> metadata) {
    if (file instanceof HadoopOutputFile) {
      options.fileSystem(((HadoopOutputFile) file).getFileSystem());
    } else {
      options.fileSystem(new FileIOFSUtil.OutputFileSystem(file));
    }
    final Path locPath = new Path(file.location());
    final Writer writer;

    try {
      writer = OrcFile.createWriter(locPath, options);
    } catch (IOException ioe) {
      throw new RuntimeIOException(ioe, "Can't create file %s", locPath);
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

Verify the file exists and is readable at the reported location (check FileIO, credentials, filesystem config)
Check that the file's ORC footer is intact (file not truncated by a failed write)
Retry if the failure was transient (network/filesystem hiccup)
Fix the file URI/scheme and path construction

Example fix

// before
Reader reader = ORC.read(file.io().newInputFile("s3://bucket/missing.orc")).build();
// after
InputFile f = file.io().newInputFile(location);
if (!f.exists()) { log.warn("Skipping missing ORC file {}", location); return; }
Reader reader = ORC.read(f).build();

Defensive patterns

Strategy: try-catch

Validate before calling

InputFile f = io.newInputFile(location);
if (!f.exists()) { throw new FileNotFoundException(location); }
try (CloseableInputStream in = f.newStream()) { in.read(); } // probe readability

Try / catch

try {
  Reader reader = ORC.read(inputFile).build();
} catch (RuntimeIOException e) {
  if (e.getMessage().startsWith("Failed to open file")) {
    log.error("ORC file unreadable at {}: {}", inputFile.location(), e.getCause());
    throw new SkipCorruptFileException(inputFile.location(), e);
  } throw e;
}

Prevention

Confirm FileIO credentials and filesystem config before scans
Avoid deleting files while concurrent readers may access them (retention policies)
Validate ORC file integrity after failed/interrupted writes
Use correct URI schemes in file locations

When it happens

Trigger: ORC.read(...) or internal reader construction on a file whose location cannot be read: file deleted, wrong path/URI, no permissions, network/filesystem outage, corrupted ORC footer.

Common situations: Files removed by retention cleanup while a scan is running; wrong filesystem credentials or missing Hadoop/S3 configuration; truncated/corrupt ORC files; typo in file URI scheme.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

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