What causes "Failed to read manifest file: %s" in apache/iceberg?

Check that the reported manifest file exists and is readable in the object store; restore it if externally deleted

apache/iceberg · error · RuntimeIOException

Failed to read manifest file: %s

Error message

Failed to read manifest file: %s

What it means

In ReachableFileCleanup.findFilesToDelete, ManifestFiles.readPaths streams data-file paths from each manifest to build the set of files eligible for deletion. An IOException during that read is rethrown as RuntimeIOException naming the manifest. It indicates the manifest file could not be read.

Source

Thrown at core/src/main/java/org/apache/iceberg/ReachableFileCleanup.java:190

      Set<ManifestFile> currentManifestFiles,
      Map<Integer, PartitionSpec> specsById) {
    Set<String> filesToDelete = ConcurrentHashMap.newKeySet();

    Tasks.foreach(manifestFilesToDelete)
        .retry(3)
        .suppressFailureWhenFinished()
        .executeWith(planExecutorService)
        .onFailure(
            (item, exc) ->
                LOG.warn(
                    "Failed to determine live files in manifest {}. Retrying", item.path(), exc))
        .run(
            manifest -> {
              try (CloseableIterable<String> paths =
                  ManifestFiles.readPaths(manifest, fileIO, specsById)) {
                paths.forEach(filesToDelete::add);
              } catch (IOException e) {
                throw new RuntimeIOException(e, "Failed to read manifest file: %s", manifest);
              }
            });

    if (filesToDelete.isEmpty()) {
      return filesToDelete;
    }

    try {
      Tasks.foreach(currentManifestFiles)
          .retry(3)
          .stopOnFailure()
          .throwFailureWhenFinished()
          .executeWith(planExecutorService)
          .onFailure(
              (item, exc) ->
                  LOG.warn(
                      "Failed to determine live files in manifest {}. Retrying", item.path(), exc))
          .run(

View on GitHub (pinned to 86d9c8fc54)

Solutions

Check that the reported manifest file exists and is readable in the object store; restore it if externally deleted
Retry the expiration after resolving storage connectivity/throttling issues
Validate FileIO credentials and permissions for the table's data/metadata paths

Defensive patterns

Strategy: try-catch

Validate before calling

// check manifest readability before cleanup
ManifestFile m = /* manifest from snapshot */;
Preconditions.checkArgument(io.newInputFile(m.path()).exists(), "Missing manifest: " + m.path());

Try / catch

try {
  expireSnapshots(table).cleanExpiredFiles(true).execute();
} catch (RuntimeIOException e) {
  // message names the unreadable manifest; verify/restore it, then retry
}

Prevention

Never remove manifest files outside of Iceberg operations
Validate storage permissions for metadata paths before cleanup
Handle object-store throttling with retries
Back up the metadata directory before expiration

When it happens

Trigger: expireSnapshots with file cleanup: reading paths from a candidate manifest (to decide which data files to delete) fails with IOException from the underlying FileIO.

Common situations: Corrupted or truncated manifest files; object-store outages or throttling during expiration; externally deleted manifest objects; permission/credential misconfiguration on the table location.

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

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