apache/iceberg · error · IllegalStateException

Cannot process unknown snapshot operation: ${op.toLowerCase(

Error message

Cannot process unknown snapshot operation: ${op.toLowerCase(Locale.ROOT)} (snapshot id ${snapshot.snapshotId()})

What it means

BaseSparkMicroBatchPlanner.shouldProcess switches on the snapshot operation to decide whether a snapshot advances the stream offset. The default branch throws IllegalStateException for operations not covered by the streaming-skip options, i.e. snapshot summaries with an unexpected or newly added operation value.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/source/BaseSparkMicroBatchPlanner.java:76

        return true;
      case DataOperations.REPLACE:
        return false;
      case DataOperations.DELETE:
        Preconditions.checkState(
            readConf.streamingSkipDeleteSnapshots(),
            "Cannot process delete snapshot: %s, to ignore deletes, set %s=true",
            snapshot.snapshotId(),
            SparkReadOptions.STREAMING_SKIP_DELETE_SNAPSHOTS);
        return false;
      case DataOperations.OVERWRITE:
        Preconditions.checkState(
            readConf.streamingSkipOverwriteSnapshots(),
            "Cannot process overwrite snapshot: %s, to ignore overwrites, set %s=true",
            snapshot.snapshotId(),
            SparkReadOptions.STREAMING_SKIP_OVERWRITE_SNAPSHOTS);
        return false;
      default:
        throw new IllegalStateException(
            String.format(
                "Cannot process unknown snapshot operation: %s (snapshot id %s)",
                op.toLowerCase(Locale.ROOT), snapshot.snapshotId()));
    }
  }

  /**
   * Get the next snapshot skipping over rewrite and delete snapshots. Async must handle nulls.
   *
   * @param curSnapshot the current snapshot
   * @return the next valid snapshot (not a rewrite or delete snapshot), returns null if all
   *     remaining snapshots should be skipped.
   */
  protected Snapshot nextValidSnapshot(Snapshot curSnapshot) {
    Snapshot nextSnapshot;
    // if there were no valid snapshots, check for an initialOffset again
    if (curSnapshot == null) {
      StreamingOffset startingOffset =

View on GitHub (pinned to 86d9c8fc54)

Solutions

Inspect the offending snapshot's summary.operation to identify the unexpected value.
Upgrade Spark/Iceberg runtime to a version that understands the new operation type.
Exclude or archive the offending snapshot/table branch; re-point the stream to a snapshot before it (set streaming-from-snapshot-id).
If produced by external tooling, fix the writer so it emits valid Iceberg operations.

Defensive patterns

Strategy: validation

Validate before calling

Table table = sparkTable.loadedTable();
for (Snapshot snap : table.snapshots()) {
  String op = snap.operation();
  if (!"append".equals(op) && !"replace".equals(op)
      && !"overwrite".equals(op) && !"delete".equals(op)) {
    throw new IllegalStateException("Snapshot " + snap.snapshotId() + " has unsupported op: " + op);
  }
}

Try / catch

try {
  streamingDf.writeStream().start();
} catch (StreamingQueryException e) {
  if (String.valueOf(e.getCause() != null ? e.getCause().getMessage() : null)
      .startsWith("Cannot process unknown snapshot operation")) {
    // upgrade Iceberg or exclude the offending snapshot
  } else { throw e; }
}

Prevention

Keep reader and writer Iceberg versions in sync.
Only write tables with standard Iceberg tooling.
Set streaming skip options (e.g. streaming-skip-overwrite-snapshots) where appropriate so known ops are handled.

When it happens

Trigger: A snapshot whose summary operation is not append/replace/overwrite/delete (e.g. a future or custom operation value) is encountered by nextValidSnapshot during streaming micro-batch planning.

Common situations: Reading a table written by a newer Iceberg version or non-Iceberg tooling that emits a new snapshot operation type; corrupted snapshot summaries.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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