apache/iceberg · error · CatalogException

Failed to list partitions of table %s

Error message

Failed to list partitions of table %s

What it means

listPartitions enumerates partitions by planning file scans over the Iceberg table and extracting partition values from each data file. If the underlying scan planning I/O fails (IOException from the FileIO layer), it is wrapped into a CatalogException with message 'Failed to list partitions of table %s'.

Source

Thrown at flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java:833

    Table table = loadIcebergTable(tablePath);

    if (table.spec().isUnpartitioned()) {
      throw new TableNotPartitionedException(icebergCatalog.name(), tablePath);
    }

    Set<CatalogPartitionSpec> set = Sets.newHashSet();
    try (CloseableIterable<FileScanTask> tasks = table.newScan().planFiles()) {
      for (DataFile dataFile : CloseableIterable.transform(tasks, FileScanTask::file)) {
        Map<String, String> map = Maps.newHashMap();
        StructLike structLike = dataFile.partition();
        PartitionSpec spec = table.specs().get(dataFile.specId());
        for (int i = 0; i < structLike.size(); i++) {
          map.put(spec.fields().get(i).name(), String.valueOf(structLike.get(i, Object.class)));
        }
        set.add(new CatalogPartitionSpec(map));
      }
    } catch (IOException e) {
      throw new CatalogException(
          String.format("Failed to list partitions of table %s", tablePath), e);
    }

    return Lists.newArrayList(set);
  }

  @Override
  public List<CatalogPartitionSpec> listPartitions(
      ObjectPath tablePath, CatalogPartitionSpec partitionSpec) throws CatalogException {
    throw new UnsupportedOperationException();
  }

  @Override
  public List<CatalogPartitionSpec> listPartitionsByFilter(
      ObjectPath tablePath, List<Expression> filters) throws CatalogException {
    throw new UnsupportedOperationException();
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Inspect the wrapped IOException cause to identify the storage access failure
2. Verify catalog FileIO/warehouse configuration and credentials for the table location
3. Confirm table metadata files and manifests exist and are readable at the table location
4. Retry if the failure was transient (network); otherwise repair or reload table metadata

Example fix

// before
List<CatalogPartitionSpec> parts = catalog.listPartitions(tablePath);

// after
try {
  List<CatalogPartitionSpec> parts = catalog.listPartitions(tablePath);
} catch (CatalogException e) {
  LOG.warn("Partition listing failed for {}", tablePath, e.getCause());
  throw e;
}

// verify table location is reachable before listing:
table.io().newInputFile(table.location()).getLength();

try { catalog.listPartitions(tablePath); } catch (CatalogException e) { LOG.error("Partition listing failed: {}", e.getCause()); }

When it happens

Trigger: Calling listPartitions when the table's metadata/data files cannot be read: missing files, unreachable storage (S3/HDFS credentials, network), corrupt manifest lists, or FileIO misconfiguration.

Common situations: Expired cloud credentials; HDFS NameNode unreachable; table metadata pointing to deleted snapshots; wrong warehouse/io property configuration on the catalog.

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 partitions of table %s
• Failed to plan files for main index
• Failed to plan files for main index
• Failed to process tasks iterable
• Failed to plan files for main index

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