apache/iceberg · error · IllegalArgumentException

Unsupported changelog scan task type: + task.getClass().getN

Error message

Unsupported changelog scan task type: + task.getClass().getName()

What it means

openChangelogScanTask throws IllegalArgumentException when the ChangelogScanTask subtype matches none of the known classes (AddedRowsScanTask, DeletedRowsScanTask, DeletedDataFileScanTask). This signals a task type introduced by a newer Iceberg core that this Spark reader doesn't know.

Source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/source/ChangelogRowReader.java:114

    metadataRow.update(0, UTF8String.fromString(task.operation().name()));
    metadataRow.update(1, task.changeOrdinal());
    metadataRow.update(2, task.commitSnapshotId());

    return metadataRow;
  }

  private CloseableIterable<InternalRow> openChangelogScanTask(ChangelogScanTask task) {
    if (task instanceof AddedRowsScanTask) {
      return openAddedRowsScanTask((AddedRowsScanTask) task);

    } else if (task instanceof DeletedRowsScanTask) {
      throw new UnsupportedOperationException("Deleted rows scan task is not supported yet");

    } else if (task instanceof DeletedDataFileScanTask) {
      return openDeletedDataFileScanTask((DeletedDataFileScanTask) task);

    } else {
      throw new IllegalArgumentException(
          "Unsupported changelog scan task type: " + task.getClass().getName());
    }
  }

  CloseableIterable<InternalRow> openAddedRowsScanTask(AddedRowsScanTask task) {
    String filePath = task.file().location();
    SparkDeleteFilter deletes = new SparkDeleteFilter(filePath, task.deletes(), counter(), true);
    return deletes.filter(rows(task, deletes.requiredSchema()));
  }

  private CloseableIterable<InternalRow> openDeletedDataFileScanTask(DeletedDataFileScanTask task) {
    String filePath = task.file().location();
    SparkDeleteFilter deletes =
        new SparkDeleteFilter(filePath, task.existingDeletes(), counter(), true);
    return deletes.filter(rows(task, deletes.requiredSchema()));
  }

  private CloseableIterable<InternalRow> rows(ContentScanTask<DataFile> task, Schema readSchema) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Align all Iceberg dependencies to one version — use the shaded iceberg-spark-runtime jar only.
2. Check classpath for duplicate/conflicting iceberg jars (spark.jars.packages, conf).
3. Remove custom ChangelogScanTask implementations or add support for them in the reader.
4. Report/reproduce with the task class name from the message to identify the producing version.

Example fix

// before
--packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.0,org.apache.iceberg:iceberg-core:1.7.0
// after
--packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.7.0

// verify a single aligned Iceberg runtime before starting the job
String v = org.apache.iceberg.IcebergBuild.version();
assert Class.forName("org.apache.iceberg.spark.source.ChangelogRowReader") != null;

// narrow task types before reading
if (!(task instanceof AddedRowsScanTask) && !(task instanceof DeletedDataFileScanTask)) {
  throw new IllegalStateException("unsupported task type, upgrade runtime: " + task.getClass().getName());
}

try { read(); } catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unsupported changelog scan task type")) failFastWithVersionReport(e);
  else throw e;
}

When it happens

Trigger: A changelog scan produces a task type unrecognized by the installed Spark integration — typically after mixing Iceberg runtime versions (core newer than spark module) or custom ChangelogScanTask implementations.

Common situations: Version skew: iceberg-core upgraded but iceberg-spark-runtime not; custom forks adding scan task types; classpath containing two Iceberg versions.

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

• AS OF is not supported for changelogs
• Unknown Spark table type: %s
• Deleted rows scan task is not supported yet
• Unsupported changelog scan task type: ${task.getClass().getN
• Failed to close changelog scan: ${scan}

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