apache/iceberg · error · IllegalStateException

Cannot process unknown snapshot operation: %s (snapshot id %

Error message

Cannot process unknown snapshot operation: %s (snapshot id %s)

What it means

BaseSparkMicroBatchPlanner.shouldProcess throws this IllegalStateException in the default branch of the snapshot-operation switch, meaning a snapshot's operation is not one of the recognized streaming operations (append, overwrite, delete, replace, etc.). It guards against the snapshot summary exposing an operation this planner version does not understand.

Source

Thrown at spark/v4.2/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

1. Upgrade the Iceberg runtime to a version that recognizes the new snapshot operation
2. Inspect snapshot.operation in the offending snapshot summary to identify the producer
3. Check for external tools writing snapshots to the table
4. If the operation is legitimate and should be skipped, track/report an Iceberg issue rather than bypassing

Example fix

// before
// reading a table with a new operation on an old runtime
// after
// upgrade dependency
implementation("org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:latest")

Set<Operation> known = Set.of(Operation.APPEND, Operation.OVERWRITE, Operation.DELETE, Operation.REPLACE);
if (!known.contains(snapshot.operation())) throw new IllegalStateException("unsupported op: " + snapshot.operation());

boolean isKnown(Operation op) { return op == Operation.APPEND || op == Operation.OVERWRITE || op == Operation.DELETE || op == Operation.REPLACE; }

When it happens

Trigger: nextValidSnapshot encounters a snapshot whose SnapshotSummary operation (case-insensitively) matches no known enum value, e.g. produced by a newer Iceberg writer version or a corrupted/foreign snapshot.

Common situations: A table written by a newer Iceberg version introducing a new snapshot operation is read by an older Spark integration; tables written by non-Iceberg tooling injecting unusual snapshots.

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

• Cannot process unknown snapshot operation: ${op.toLowerCase(
• Cannot process unknown snapshot operation: %s (snapshot id %
• Cannot process unknown snapshot operation: %s (snapshot id %
• Cannot apply non-unique WAP ID. Found multiple snapshots wit
• Cannot apply unknown WAP ID '${wapId}'

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