apache/iceberg · error · IllegalArgumentException

Entries must have explicit snapshot ids if inherited metadat

Error message

Entries must have explicit snapshot ids if inherited metadata is empty

What it means

InheritableMetadataFactory.EmptyInheritableMetadata.apply() performs no inheritance, so a manifest entry without its own explicit snapshotId cannot be attributed to any snapshot and is rejected. This is a defensive check ensuring entries are never processed with unknown snapshot provenance.

Source

Thrown at core/src/main/java/org/apache/iceberg/InheritableMetadataFactory.java:116

    private CopyMetadata(long snapshotId) {
      this.snapshotId = snapshotId;
    }

    @Override
    public <F extends ContentFile<F>> ManifestEntry<F> apply(ManifestEntry<F> manifestEntry) {
      manifestEntry.setSnapshotId(snapshotId);
      return manifestEntry;
    }
  }

  static class EmptyInheritableMetadata implements InheritableMetadata {

    private EmptyInheritableMetadata() {}

    @Override
    public <F extends ContentFile<F>> ManifestEntry<F> apply(ManifestEntry<F> manifestEntry) {
      if (manifestEntry.snapshotId() == null) {
        throw new IllegalArgumentException(
            "Entries must have explicit snapshot ids if inherited metadata is empty");
      }
      return manifestEntry;
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Set the snapshot id explicitly on the manifest entry before applying inheritable metadata
2. Read manifests with a ManifestReader that inherits metadata from the manifest list (default) rather than empty metadata
3. Repair/rewrite corrupt manifest files missing snapshot-id fields
4. Use try-with-resources ManifestReader.read(manifest) with the manifest's own snapshot id passed in

Example fix

// before
ManifestEntry<DataFile> entry = new ManifestEntry<>(...);
entry.setSnapshotId(null);
emptyMetadata.apply(entry); // throws
// after
entry.setSnapshotId(manifest.snapshotId());
emptyMetadata.apply(entry);

if (entry.snapshotId() == null) {
  entry.setSnapshotId(manifestSnapshotId); // inherit before applying
}

try {
  factory.apply(entry);
} catch (IllegalArgumentException e) {
  LOG.error("Manifest entry missing snapshot id: {}", entry.file().location(), e);
}

When it happens

Trigger: Reading manifest entries via a reader configured to not inherit metadata (e.g., ManifestReader without inheritable metadata set, or using EmptyInheritableMetadata) when an entry's snapshot-id field is null in the manifest file.

Common situations: Corrupt or hand-crafted manifest files missing snapshot-id; v1-era manifests read with inheritance disabled; custom code constructing ManifestEntry without snapshotId and applying it directly.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Failed to close manifest reader
• ORC schema does not contain Iceberg IDs
• Can't retrieve values from an empty struct
• Can't modify an empty struct
• %s doesn't implement cleanupLevel

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