apache/iceberg · error · RuntimeIOException

Failed to create Parquet reader

Error message

Failed to create Parquet reader

What it means

ParquetIterable lazily opens an underlying ParquetReader when iterator() is first called. If building that reader (opening the file, reading metadata) throws an IOException, it is wrapped as a RuntimeIOException with this message. The error means the Parquet file could not be opened for reading.

Source

Thrown at parquet/src/main/java/org/apache/iceberg/parquet/ParquetIterable.java:43

import org.apache.iceberg.io.CloseableIterable;
import org.apache.iceberg.io.CloseableIterator;
import org.apache.parquet.hadoop.ParquetReader;

public class ParquetIterable<T> extends CloseableGroup implements CloseableIterable<T> {
  private final ParquetReader.Builder<T> builder;

  ParquetIterable(ParquetReader.Builder<T> builder) {
    this.builder = builder;
  }

  @Override
  public CloseableIterator<T> iterator() {
    try {
      ParquetReader<T> reader = builder.build();
      addCloseable(reader);
      return new ParquetIterator<>(reader);
    } catch (IOException e) {
      throw new RuntimeIOException(e, "Failed to create Parquet reader");
    }
  }

  private static class ParquetIterator<T> implements CloseableIterator<T> {
    private final ParquetReader<T> parquet;
    private boolean needsAdvance = false;
    private boolean hasNext = false;
    private T next;

    ParquetIterator(ParquetReader<T> parquet) {
      this.parquet = parquet;
      this.next = advance();
    }

    @Override
    public boolean hasNext() {
      if (needsAdvance) {
        this.next = advance();

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the input file path/location exists and is readable before creating the iterable.
2. Inspect the wrapped IOException cause for the specific open/read failure.
3. Confirm credentials and filesystem configuration for the storage layer.
4. If the file is corrupt, rewrite it from source data or recover via a previous snapshot.

Example fix

// before
CloseableIterator<T> it = ParquetIterable.create(builder).iterator(); // throws at open
// after
if (fileSystem.exists(new Path(location))) {
  CloseableIterator<T> it = ParquetIterable.create(builder).iterator();
}

if (!fileSystem.exists(new Path(location))) {
  throw new FileNotFoundException(location);
}

try {
  return iterable.iterator();
} catch (RuntimeIOException e) {
  throw new IOException("Cannot open parquet file", e.getCause());
}

When it happens

Trigger: Calling iterator() on a ParquetIterable whose builder points at a missing, corrupt, or unreadable file; underlying ParquetReader.Builder.build() throws IOException (file open failure, footer read failure, truncated/corrupt file).

Common situations: Input file deleted or path mistyped; file truncated by a failed write; wrong Hadoop configuration so InputFile cannot be opened; permission errors on HDFS/S3; schema mismatch detected during reader construction.

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

• Unable to read the metrics of the Parquet file:
• Failed to read from input stream
• Failed to read bytes from stream
• Error reading mini block.
• Failed to read binary data

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