apache/iceberg · error · UncheckedIOException

Failed to read manifest:

Error message

Failed to read manifest: 

What it means

readDVEntries() iterates a manifest's delete files to collect existing deletion vectors; an IOException from opening/reading the manifest data is wrapped in UncheckedIOException with the manifest path. It means table metadata content could not be read from storage.

Source

Thrown at flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/maintenance/operator/EqualityConvertDVWriter.java:312

    }

    return anyPartition;
  }

  private void readDVEntries(
      ManifestFile manifest, Set<String> filterPaths, Map<String, DeleteFile> out) {
    manifestsRead++;
    try (ManifestReader<DeleteFile> reader =
        ManifestFiles.readDeleteManifest(manifest, table.io(), table.specs())) {
      for (DeleteFile deleteFile : reader) {
        if (ContentFileUtil.isDV(deleteFile)
            && deleteFile.referencedDataFile() != null
            && filterPaths.contains(deleteFile.referencedDataFile())) {
          out.put(deleteFile.referencedDataFile(), deleteFile);
        }
      }
    } catch (IOException e) {
      throw new UncheckedIOException("Failed to read manifest: " + manifest.path(), e);
    }
  }

  @VisibleForTesting
  int manifestsReadLastCycle() {
    return manifestsRead;
  }

  @VisibleForTesting
  int retainedStateSize() {
    return positionsByFile.size();
  }

  private PositionDeleteIndex loadPreviousDV(String dataFilePath, Map<String, DeleteFile> dvs) {
    DeleteFile existingDV = dvs.get(dataFilePath);
    if (existingDV == null) {
      return null;
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Retry the maintenance task — most storage errors are transient
2. Verify the manifest still exists and wasn't removed by expireSnapshots running concurrently
3. Check FileIO credentials/permissions on the TaskManager for the table location
4. Inspect the cause (IOException chain) for the storage-level error (403, 404, timeout)
5. Enable retries on the object store client (S3 retry config, HDFS client settings)

// preflight: manifest reachable via FileIO
boolean exists = table.io().newInputFile(manifestPath).exists();

try {
  planner.plan();
} catch (UncheckedIOException e) {
  if (e.getMessage().startsWith("Failed to read manifest: ")) {
    // transient storage error: retry with backoff; else verify snapshot validity
  } else { throw e; }
}

When it happens

Trigger: readDVEntries called during collectExistingDVs while the underlying FileIO fails to open or stream the manifest file — deleted object, expired snapshot cleanup, credentials revoked, or transient S3/HDFS errors.

Common situations: Object store throttling or 5xx during manifest reads; snapshot expiration (orphan/expireSnapshots) removing a still-referenced manifest; missing/expired cloud credentials on TaskManagers; HDFS NameNode unavailability.

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 read manifest file: %s
• Failed to write manifest
• Failed to list partitions of table %s
• Failed to read manifest: <manifest.path()>
• Failed to read manifest:

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