apache/iceberg · warning

Encountered invalid summary for snapshot {}: the field 'oper

Error message

Encountered invalid summary for snapshot {}: the field 'operation' is required but missing, setting 'operation' to overwrite

What it means

SnapshotParser.fromJson requires the 'operation' field in a snapshot summary. To stay forward/backward compatible with metadata written by buggy or very old writers, a missing operation is not rejected: a warning is logged and the operation defaults to 'overwrite' so summary parsing succeeds. The snapshot loads normally, but the operation value is a synthesized default.

Source

Thrown at core/src/main/java/org/apache/iceberg/SnapshotParser.java:164

          sNode);

      if (sNode.size() > 0) {
        ImmutableMap.Builder<String, String> builder = ImmutableMap.builder();
        Iterator<String> fields = sNode.fieldNames();
        while (fields.hasNext()) {
          String field = fields.next();
          if (field.equals(OPERATION)) {
            operation = JsonUtil.getString(OPERATION, sNode);
          } else {
            builder.put(field, JsonUtil.getString(field, sNode));
          }
        }
        summary = builder.build();

        // When the operation is not found, default to overwrite
        // to ensure that we can read the summary without raising an exception
        if (operation == null) {
          LOG.warn(
              "Encountered invalid summary for snapshot {}: the field 'operation' is required but missing, setting 'operation' to overwrite",
              snapshotId);
          operation = DataOperations.OVERWRITE;
        }
      }
    }

    Integer schemaId = JsonUtil.getIntOrNull(SCHEMA_ID, node);

    Long firstRowId = JsonUtil.getLongOrNull(FIRST_ROW_ID, node);
    Long addedRows = JsonUtil.getLongOrNull(ADDED_ROWS, node);

    String keyId = JsonUtil.getStringOrNull(KEY_ID, node);

    if (node.has(MANIFEST_LIST)) {
      // the manifest list is stored in a manifest list file
      String manifestList = JsonUtil.getString(MANIFEST_LIST, node);
      return new BaseSnapshot(

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. No action required to read: the snapshot loads with operation='overwrite'.
2. Fix the writer that produced snapshots without an operation; every new snapshot must set DataOperations in its summary.
3. Write new commits (e.g. a trivial rewrite) so a valid snapshot becomes current, or repair the metadata JSON to add 'operation'.
4. If the wrong default matters for your logic, validate table.snapshots() summaries after loading migrated tables.

Example fix

// before: broken summary written by a custom writer
ImmutableMap.of("added-data-files", "3")
// after: always include the operation
ImmutableMap.of(
    "operation", DataOperations.APPEND,
    "added-data-files", "3")

for (Snapshot s : table.snapshots()) {
  Preconditions.checkState(s.summary() != null && s.summary().get("operation") != null,
      "Snapshot " + s.snapshotId() + " summary missing operation");
}

boolean hasOperation(Snapshot s) {
  return s.summary() != null && s.summary().get("operation") != null;
}

// library never throws here; if the default matters:
Snapshot s = table.currentSnapshot();
if (!hasOperation(s)) { /* treat as overwrite or reject the table */ }

When it happens

Trigger: Reading table metadata containing a snapshot whose summary lacks the 'operation' key — e.g. metadata written by a broken custom writer, manually edited metadata JSON, or corrupt/partial summary objects from an old Iceberg version.

Common situations: Custom engines writing snapshots without building summaries correctly, metadata surgery performed by external scripts, and reading legacy tables migrated from very old Iceberg builds.

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

• Unexpected null order: ${nullOrderingAsString}
• Cannot process unknown snapshot operation: %s (snapshot id %
• Cannot process unknown snapshot operation: %s (snapshot id %
• this.getClass().getName() + " doesn't implement removedDelet
• String.format("Invalid snapshot ref type: %s", snapshotRefTy

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