apache/iceberg · error · IllegalArgumentException

Unexpected entry status: ${entry.status}

Error message

Unexpected entry status: ${entry.status}

What it means

When materializing changelog entries, each manifest entry status (ADDED=1, EXISTING=0, DELETED=2) must map to a changelog insert/delete record. Any other status value is a spec violation and triggers this IllegalArgumentException. In practice this indicates corrupt manifest data or a newer format version read by an older client.

Source

Thrown at core/src/main/java/org/apache/iceberg/BaseIncrementalChangelogScan.java:178

                    commitSnapshotId,
                    dataFile,
                    NO_DELETES,
                    context.schemaAsString(),
                    context.specAsString(),
                    context.residuals());

              case DELETED:
                return new BaseDeletedDataFileScanTask(
                    changeOrdinal,
                    commitSnapshotId,
                    dataFile,
                    NO_DELETES,
                    context.schemaAsString(),
                    context.specAsString(),
                    context.residuals());

              default:
                throw new IllegalArgumentException("Unexpected entry status: " + entry.status());
            }
          });
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Upgrade the Iceberg client to at least the version that wrote the table's manifests
2. Rewrite manifests/tables (rewrite_manifests procedure) to rebuild valid entries
3. Check for manual tampering with metadata files; restore from a valid snapshot/metadata checkpoint

Example fix

// before
Table table = oldClientCatalog.loadTable(ident);
// after
// upgrade dependency to match writer version, e.g. in Gradle:
// implementation 'org.apache.iceberg:iceberg-core:1.6.x' // matches table writer version
Table table = catalog.loadTable(ident);

boolean knownStatus(int status) { return status == 0 || status == 1 || status == 2; }

try { changelogScan.iterator(); } catch (IllegalArgumentException e) { logger.error("Manifest entry status unrecognized — client/table version mismatch", e); }

When it happens

Trigger: Changelog scan over snapshots whose manifest entries carry a status byte outside {0,1,2} — typically corrupt/rewritten manifests or format-version incompatibility.

Common situations: Reading tables written by a newer Iceberg version with an older client; corrupted manifest files after failed commits or manual metadata edits.

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

• Unsupported status:
• Unsupported manifest content type:${content}
• Unsorted order ID must be 0
• Sort order ID 0 is reserved for unsorted order
• Cannot create expression literal from %s: %s

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