apache/iceberg · error · RuntimeException

Unable to read the metrics of the Parquet file:

Error message

Unable to read the metrics of the Parquet file: 

What it means

Thrown by TableMigrationUtil.getParquetMetrics when reading column statistics/metrics from a Parquet file during table migration or import fails with an UncheckedIOException. Iceberg wraps the low-level IO failure in a RuntimeException that includes the file path, because import cannot proceed without metrics. The original cause chain is preserved.

Source

Thrown at data/src/main/java/org/apache/iceberg/data/TableMigrationUtil.java:230

  }

  private static Metrics getAvroMetrics(Path path, Configuration conf) {
    try {
      InputFile file = HadoopInputFile.fromPath(path, conf);
      long rowCount = Avro.rowCount(file);
      return new Metrics(rowCount, null, null, null, null);
    } catch (UncheckedIOException e) {
      throw new RuntimeException("Unable to read Avro file: " + path, e);
    }
  }

  private static Metrics getParquetMetrics(
      Path path, Configuration conf, MetricsConfig metricsSpec, NameMapping mapping) {
    try {
      InputFile file = HadoopInputFile.fromPath(path, conf);
      return ParquetUtil.fileMetrics(file, metricsSpec, mapping);
    } catch (UncheckedIOException e) {
      throw new RuntimeException("Unable to read the metrics of the Parquet file: " + path, e);
    }
  }

  private static Metrics getOrcMetrics(
      Path path, Configuration conf, MetricsConfig metricsSpec, NameMapping mapping) {
    try {
      return OrcMetrics.fromInputFile(HadoopInputFile.fromPath(path, conf), metricsSpec, mapping);
    } catch (UncheckedIOException e) {
      throw new RuntimeException("Unable to read the metrics of the Orc file: " + path, e);
    }
  }

  private static DataFile buildDataFile(
      FileStatus stat,
      List<String> partitionValues,
      PartitionSpec spec,
      Metrics metrics,
      String format) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the file path exists and is readable: run hadoop fs -ls / hdfs dfs -ls on the path printed in the message.
2. Fix Hadoop configuration/credentials for the source filesystem (core-site.xml, S3A keys, tokens) and retry.
3. If the file was deleted, re-plan the migration against a consistent snapshot or restore the file.
4. Catch the RuntimeException at the call site to skip/report bad files instead of failing the whole import.

Example fix

// before
Metrics metrics = TableMigrationUtil.getParquetMetrics(path, conf, metricsSpec, mapping);
// after
Metrics metrics;
try {
  metrics = TableMigrationUtil.getParquetMetrics(path, conf, metricsSpec, mapping);
} catch (RuntimeException e) {
  LOG.warn("Skipping unreadable parquet file {}", path, e);
  return;
}

Path p = new Path(parquetPath);
FileSystem fs = p.getFileSystem(conf);
Preconditions.checkState(fs.exists(p) && fs.getFileStatus(p).getLen() > 0, "Missing/unreadable parquet file: " + parquetPath);

try {
  Metrics m = TableMigrationUtil.getParquetMetrics(path, conf, metricsSpec, mapping);
} catch (RuntimeException e) {
  if (e.getCause() instanceof UncheckedIOException || e.getCause() instanceof IOException) {
    LOG.warn("Skipping unreadable parquet file {}", path, e);
  } else { throw e; }
}

When it happens

Trigger: Calling TableMigrationUtil.importParquet (or a Spark/Hive migration procedure) on a Parquet path whose underlying file is missing, deleted mid-read, unreadable due to permissions, or whose Hadoop configuration points at an inaccessible filesystem (e.g. wrong defaultFS, missing credentials).

Common situations: Migrating a Hive table where files were removed by compaction after planning; S3/HDFS credentials expired; snapshot paths referenced by a stale manifest; typo in warehouse path so the file does not exist.

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 Orc file:
• Failed to create Parquet reader
• Failed to read from input stream
• Failed to read bytes from stream
• Error reading mini block.

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