apache/iceberg · error · UnsupportedOperationException

Unknown transform %s is not supported

Error message

Unknown transform %s is not supported

What it means

PartitionSpecVisitor's default unknown() throws UnsupportedOperationException when the spec contains an UnknownTransform — a transform that was written by a newer Iceberg version (or a custom Transform subclass) that the current visitor cannot interpret. visit() detects UnknownTransform and calls unknown(...) with the transform's string form so implementations can either map it or fail. The throwing default means the visitor has no policy for unrecognized transforms.

Source

Thrown at api/src/main/java/org/apache/iceberg/transforms/PartitionSpecVisitor.java:89

  default T day(String sourceName, int sourceId) {
    throw new UnsupportedOperationException("Day transform is not supported");
  }

  default T hour(int fieldId, String sourceName, int sourceId) {
    return hour(sourceName, sourceId);
  }

  default T hour(String sourceName, int sourceId) {
    throw new UnsupportedOperationException("Hour transform is not supported");
  }

  default T alwaysNull(int fieldId, String sourceName, int sourceId) {
    throw new UnsupportedOperationException("Void transform is not supported");
  }

  default T unknown(int fieldId, String sourceName, int sourceId, String transform) {
    throw new UnsupportedOperationException(
        String.format("Unknown transform %s is not supported", transform));
  }

  /**
   * Visit the fields of a {@link PartitionSpec}.
   *
   * @param spec a partition spec to visit
   * @param visitor a partition spec visitor
   * @param <R> return type of the visitor
   * @return a list of the result produced by visiting each partition field
   */
  static <R> List<R> visit(PartitionSpec spec, PartitionSpecVisitor<R> visitor) {
    List<R> results = Lists.newArrayListWithExpectedSize(spec.fields().size());

    for (PartitionField field : spec.fields()) {
      results.add(visit(spec.schema(), field, visitor));
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Override unknown(int fieldId, String sourceName, int sourceId, String transform) to explicitly map or reject the unrecognized transform string
  2. Upgrade the Iceberg version so the transform resolves to a known class instead of UnknownTransform
  3. Identify the writer version from table metadata and either migrate the partition spec or use a compatible reader

Example fix

// before
default unknown() -> UnsupportedOperationException
// after
@Override
public String unknown(int fieldId, String sourceName, int sourceId, String transform) {
  throw new IllegalArgumentException("Spec uses unsupported transform " + transform
      + "; upgrade Iceberg to read this table");
}
Defensive patterns

Strategy: validation

Validate before calling

boolean hasUnknownTransform(PartitionSpec spec) {
  return spec.fields().stream().anyMatch(f -> f.transform() instanceof UnknownTransform);
}
// true means the table was written by a newer/extended Iceberg — upgrade or handle explicitly

Type guard

if (field.transform() instanceof UnknownTransform) {
  String name = field.transform().toString(); // decide policy per transform name
}

Try / catch

try {
  PartitionSpecVisitor.visit(spec, visitor);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().startsWith("Unknown transform")) {
    throw new IllegalStateException("Table written by newer Iceberg; upgrade to read spec", e);
  }
  throw e;
}

Prevention

When it happens

Trigger: PartitionSpecVisitor.visit on a table whose metadata references a transform not resolvable by the current version (e.g. table written by a newer Iceberg with a transform this build doesn't know), with a visitor lacking an unknown() override.

Common situations: Version skew: reading metadata produced by a newer Iceberg release or a vendor extension using custom transforms; rolling upgrades where an older engine reads a newer table's partition spec.

Related errors

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