apache/iceberg · error · IllegalArgumentException

Cannot update partition spec with unknown transform:

Error message

Cannot update partition spec with unknown transform: 

What it means

BaseUpdatePartitionSpec validates that every existing field's transform is one it understands; a field with an UnknownTransform cannot be migrated, so the constructor throws IllegalArgumentException. This guards the spec-update path against fields created by writers using transforms this version of Iceberg does not support.

Source

Thrown at core/src/main/java/org/apache/iceberg/BaseUpdatePartitionSpec.java:82

  BaseUpdatePartitionSpec(TableOperations ops) {
    this.ops = ops;
    this.caseSensitive = true;
    this.setAsDefault = true;
    this.base = ops.current();
    this.formatVersion = base.formatVersion();
    this.spec = base.spec();
    this.schema = spec.schema();
    this.nameToField = indexSpecByName(spec);
    this.transformToField = indexSpecByTransform(spec);
    this.lastAssignedPartitionId = base.lastAssignedPartitionId();

    spec.fields().stream()
        .filter(field -> field.transform() instanceof UnknownTransform)
        .findAny()
        .ifPresent(
            field -> {
              throw new IllegalArgumentException(
                  "Cannot update partition spec with unknown transform: " + field);
            });
  }

  /** For testing only. */
  @VisibleForTesting
  BaseUpdatePartitionSpec(int formatVersion, PartitionSpec spec) {
    this(formatVersion, spec, spec.lastAssignedFieldId());
  }

  /** For testing only. */
  @VisibleForTesting
  BaseUpdatePartitionSpec(int formatVersion, PartitionSpec spec, int lastAssignedPartitionId) {
    this.ops = null;
    this.base = null;
    this.formatVersion = formatVersion;
    this.caseSensitive = true;
    this.setAsDefault = true;

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Upgrade the Iceberg client to a version that supports the transform in the existing spec
2. Avoid calling updateSpec on tables with unsupported transform fields from this client version
3. Rewrite the spec via a compatible writer that can drop the unknown field before updating

Example fix

// before
UpdatePartitionSpec update = table.updateSpec(); // throws on UnknownTransform field
// after
if (table.spec().fields().stream().noneMatch(f -> f.transform() instanceof UnknownTransform)) {
  UpdatePartitionSpec update = table.updateSpec();
} else {
  // upgrade client or handle unsupported field
}

if (table.spec().fields().stream().anyMatch(f -> f.transform() instanceof UnknownTransform)) { throw new IllegalStateException("spec contains unsupported transform; upgrade client"); }

catch (IllegalArgumentException e) { /* upgrade client or skip spec update */ }

When it happens

Trigger: Opening UpdatePartitionSpec (e.g. table.updateSpec().addField(...)) on a table whose current partition spec contains a field with an UnknownTransform — typically written by a newer Iceberg version or a custom writer.

Common situations: Version skew: an older Iceberg client updating a spec created by a newer writer using an unrecognized transform; cross-engine writers with different transform support.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot add duplicate partition field name: %s
• Cannot find unpartitioned spec in specs:
• Unsupported manifest content type:${content}
• Unsupported changelog scan task type:
• Cannot write using unsupported transforms: %s

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