apache/iceberg · error · RuntimeIOException

Failed to read footer of file

Error message

Failed to read footer of file: %s

What it means

ParquetUtil.fileMetrics opens the Parquet file to read its footer for computing column metrics (counts, min/max, null counts). If opening the reader or reading the footer throws IOException, it is wrapped as RuntimeIOException with the file location included. It indicates the file's metadata could not be read, so metrics collection failed.

Solutions

1. Verify the file exists and is a complete, valid Parquet file at the given location.
2. Check the wrapped IOException cause; validate the file with a Parquet metadata tool.
3. Confirm storage credentials/configuration for the InputFile's filesystem.
4. If the file is corrupt, remove it from the table via Iceberg metadata operations and rewrite from a valid snapshot.

Example fix

// before
Metrics m = ParquetUtil.fileMetrics(files.newInputFile(location), metricsConfig, null);
// after
if (files.newInputFile(location).exists()) {
  Metrics m = ParquetUtil.fileMetrics(files.newInputFile(location), metricsConfig, null);
}

InputFile f = files.newInputFile(location);
if (!f.exists()) {
  throw new FileNotFoundException("Missing parquet file: " + location);
}

try {
  return ParquetUtil.fileMetrics(file, metricsConfig, nameMapping);
} catch (RuntimeIOException e) {
  LOG.error("Cannot read footer of {}", file.location(), e.getCause());
  throw e;
}

When it happens

Trigger: Calling ParquetUtil.fileMetrics(InputFile, MetricsConfig, NameMapping) where ParquetFileReader.open fails (file missing/unreadable) or reader.getFooter() fails (corrupt/truncated footer, not a Parquet file).

Common situations: Pointing metrics collection at a non-Parquet or truncated file; missing storage credentials; file deleted between planning and metrics computation; corrupt files from interrupted writes.

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 create Parquet reader
• OptionWriter should only expect at most one field metric…
• Unable to read the metrics of the Parquet file:
• AlwaysFalse is a placeholder only
• AlwaysTrue is a placeholder only

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

Appendix: source

Thrown at parquet/src/main/java/org/apache/iceberg/parquet/ParquetUtil.java:67

import org.apache.parquet.schema.MessageType;
import org.apache.parquet.schema.PrimitiveType;

public class ParquetUtil {
  // not meant to be instantiated
  private ParquetUtil() {}

  private static final long UNIX_EPOCH_JULIAN = 2_440_588L;

  public static Metrics fileMetrics(InputFile file, MetricsConfig metricsConfig) {
    return fileMetrics(file, metricsConfig, null);
  }

  public static Metrics fileMetrics(
      InputFile file, MetricsConfig metricsConfig, NameMapping nameMapping) {
    try (ParquetFileReader reader = ParquetFileReader.open(ParquetIO.file(file))) {
      return footerMetrics(reader.getFooter(), Stream.empty(), metricsConfig, nameMapping);
    } catch (IOException e) {
      throw new RuntimeIOException(e, "Failed to read footer of file: %s", file.location());
    }
  }

  public static Metrics footerMetrics(
      ParquetMetadata metadata, Stream<FieldMetrics<?>> fieldMetrics, MetricsConfig metricsConfig) {
    return footerMetrics(metadata, fieldMetrics, metricsConfig, null);
  }

  public static Metrics footerMetrics(
      ParquetMetadata metadata,
      Stream<FieldMetrics<?>> fieldMetrics,
      MetricsConfig metricsConfig,
      NameMapping nameMapping) {
    Preconditions.checkNotNull(fieldMetrics, "fieldMetrics should not be null");
    MessageType parquetTypeWithIds = getParquetTypeWithIds(metadata, nameMapping);
    Schema fileSchema = ParquetSchemaUtil.convertAndPrune(parquetTypeWithIds);
    return ParquetMetrics.metrics(
        fileSchema, parquetTypeWithIds, metricsConfig, metadata, fieldMetrics);

View on GitHub (pinned to 86d9c8fc54)