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

The final else branch of openChangelogScanTask throws IllegalArgumentException when the ChangelogScanTask instance matches none of the known subtypes. This guards against task types introduced by newer Iceberg versions that this reader does not recognize.

Source

Thrown at spark/v3.5/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

Align all Iceberg jars (core, api, spark) to the same version to avoid unknown task types.
Check the class name in the message; search Iceberg for the task type and upgrade to a version that handles it.
Remove custom task implementations from the classpath if any.

Example fix

// before: mixed iceberg-core 1.6 with iceberg-spark 1.5 jars
// after: use a single managed version
implementation("org.apache.iceberg:iceberg-spark-3.5_2.12:1.6.0")

Defensive patterns

Strategy: try-catch

Validate before calling

Map<String,String> versions = classpathIcebergVersions(); // e.g. inspect jar manifests
Set<String> distinct = new HashSet<>(versions.values());
if (distinct.size() > 1) throw new IllegalStateException("Mixed Iceberg versions on classpath: " + distinct);

Type guard

boolean isKnownChangelogTask(ChangelogScanTask task) {
  return task instanceof AddedRowsScanTask
      || task instanceof DeletedRowsScanTask
      || task instanceof DeletedDataFileScanTask;
}

Try / catch

try {
  changelogDf.writeStream().start();
} catch (StreamingQueryException e) {
  if (e.getCause() instanceof IllegalArgumentException
      && e.getCause().getMessage().startsWith("Unsupported changelog scan task type")) {
    // align Iceberg jar versions, then restart
  } else { throw e; }
}

Prevention

Use one managed Iceberg version for all modules in the dependency tree.
Avoid shading multiple Iceberg versions into the job classpath.
Upgrade reader runtime before enabling new writer features.

When it happens

Trigger: openChangelogScanTask receives a ChangelogScanTask implementation that is not AddedRowsScanTask, DeletedRowsScanTask, or DeletedDataFileScanTask — e.g. a new task type from a newer core version mixed with an older Spark runtime.

Common situations: Version skew between iceberg-core/iceberg-spark jars on the classpath, or custom ChangelogScanTask implementations.

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/5c45eb2811de1b9d. Report an issue: GitHub.