apache/iceberg · error · IllegalStateException

Unexpected entry status, not added or deleted: %s

Error message

Unexpected entry status, not added or deleted: %s

What it means

When caching data-file changes, BaseSnapshot expects each manifest entry status to be ADDED or DELETED; any other status (e.g. EXISTING) hits the default branch and throws IllegalStateException. This guards a broken invariant: change-caching scans only v1 manifests where added/removed changes are representable, so other statuses indicate corrupt or unexpected data.

Source

Thrown at core/src/main/java/org/apache/iceberg/BaseSnapshot.java:319

    ImmutableList.Builder<DataFile> adds = ImmutableList.builder();
    ImmutableList.Builder<DataFile> deletes = ImmutableList.builder();

    // read only manifests that were created by this snapshot
    Iterable<ManifestFile> changedManifests =
        Iterables.filter(
            dataManifests(fileIO), manifest -> Objects.equal(manifest.snapshotId(), snapshotId));
    try (CloseableIterable<ManifestEntry<DataFile>> entries =
        new ManifestGroup(fileIO, changedManifests).ignoreExisting().entries()) {
      for (ManifestEntry<DataFile> entry : entries) {
        switch (entry.status()) {
          case ADDED:
            adds.add(entry.file().copy());
            break;
          case DELETED:
            deletes.add(entry.file().copyWithoutStats());
            break;
          default:
            throw new IllegalStateException(
                "Unexpected entry status, not added or deleted: " + entry);
        }
      }
    } catch (IOException e) {
      throw new RuntimeIOException(e, "Failed to close entries while caching changes");
    }

    this.addedDataFiles = adds.build();
    this.removedDataFiles = deletes.build();
  }

  @Override
  public boolean equals(Object o) {
    if (this == o) {
      return true;
    }

    if (o instanceof BaseSnapshot) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Verify the snapshot's manifests come from a valid append/overwrite snapshot (operations().current().currentSnapshot().snapshotId())
  2. Rebuild/repair table metadata if manifests are corrupt (e.g. from a metadata backup or add_files procedure)
  3. Upgrade Iceberg if the producing operation was from an older buggy version
  4. Don't call addedDataFiles/removedDataFiles on snapshots (e.g. overflow/rollback) that don't represent direct file changes

Example fix

// before: uses arbitrary snapshot id
Snapshot s = table.snapshot(someOldSnapshotId);
s.addedDataFiles();
// after: only direct-change snapshots
Snapshot s = table.currentSnapshot();
if (s.operation().equals(DataOperations.APPEND) || s.operation().equals(DataOperations.OVERWRITE)) {
  s.addedDataFiles();
}
Defensive patterns

Strategy: validation

Validate before calling

if (!Set.of(DataOperations.APPEND, DataOperations.OVERWRITE).contains(snapshot.operation())) {
  throw new IllegalStateException("addedDataFiles only valid for append/overwrite snapshots");
}

Type guard

boolean isDeltaSnapshot(Snapshot s) { return DataOperations.APPEND.equals(s.operation()) || DataOperations.OVERWRITE.equals(s.operation()); }

Try / catch

try { snapshot.addedDataFiles(); } catch (IllegalStateException e) { /* fall back to full manifest diff */ }

Prevention

When it happens

Trigger: Calling addedDataFiles()/removedDataFiles() on a snapshot whose manifests contain entries with EXISTING status — e.g. snapshots produced by operations that copied entries, or a corrupt manifest list pointing to the wrong (non-delta) manifest.

Common situations: Hand-built or migrated metadata; reading v1 tables with tooling that mislabeled manifests; a bug in a custom snapshot producer that emits existing entries where deltas are expected.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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