apache/iceberg · error · UncheckedIOException

Unable to list files in partition:

Error message

Unable to list files in partition: 

What it means

TableMigrationUtil.listPartition wraps any IOException thrown while listing the partition's files (filesystem listing, parallel metric computation) into an UncheckedIOException 'Unable to list files in partition: <partitionUri>'. It indicates the partition directory could not be read, not a format problem.

Solutions

1. Read the chained cause to find whether it's a FileNotFoundException, access denied, or connection error.
2. Verify the partition URI exists and is correct (e.g. hadoop fs -ls <partitionUri>).
3. Fix filesystem credentials/permissions for the migration job's identity.
4. Retry if the cause indicates a transient storage error; exclude corrupt partitions otherwise.

Example fix

// before: migration fails wholesale on one bad partition
List<DataFile> files = TableMigrationUtil.listPartition(...);

// after: validate and skip missing partitions first
if (fs.exists(partitionPath)) {
  List<DataFile> files = TableMigrationUtil.listPartition(...);
}

if (!fs.exists(new Path(partitionUri))) {
  throw new IllegalArgumentException("Partition does not exist: " + partitionUri);
}
fs.access(new Path(partitionUri), FsAction.READ);

try {
  List<DataFile> files = TableMigrationUtil.listPartition(...);
} catch (UncheckedIOException e) {
  if (e.getCause() instanceof FileNotFoundException) { skipPartition(); }
  else if (isTransient(e.getCause())) { retry(); }
  else { throw e; }
}

When it happens

Trigger: Calling listPartition for a partition URI that doesn't exist, is inaccessible (permissions/auth), or whose underlying filesystem errors during listing or during getOrcMetrics/getParquetMetrics IO work inside the Tasks.foreach.

Common situations: HDFS/S3 outages or throttling during migration; wrong partition path in the source table metadata; expired cloud credentials; missing Kerberos/permissions on the Hive warehouse directory.

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 list namespace under
• Failed to list tables under
• Can't create file
• Cannot read manifest list file
• Exception listing files for

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

Appendix: source

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

              Metrics metrics =
                  getParquetMetrics(fileStatus.get(index).getPath(), conf, metricsSpec, mapping);
              datafiles[index] =
                  buildDataFile(fileStatus.get(index), partitionValues, spec, metrics, "parquet");
            });
      } else if (format.contains("orc")) {
        task.run(
            index -> {
              Metrics metrics =
                  getOrcMetrics(fileStatus.get(index).getPath(), conf, metricsSpec, mapping);
              datafiles[index] =
                  buildDataFile(fileStatus.get(index), partitionValues, spec, metrics, "orc");
            });
      } else {
        throw new UnsupportedOperationException("Unknown partition format: " + format);
      }
      return Arrays.asList(datafiles);
    } catch (IOException e) {
      throw new UncheckedIOException("Unable to list files in partition: " + partitionUri, e);
    } finally {
      if (service != null) {
        service.shutdown();
      }
    }
  }

  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(

View on GitHub (pinned to 86d9c8fc54)