What causes "Unknown transform %s is not supported" in apache/iceberg?

Unknown transform %s is not supported

Error message

Unknown transform %s is not supported

What it means

SortOrderVisitor's default unknown() throws UnsupportedOperationException when a sort-order field uses a transform the visitor cannot interpret (an UnknownTransform, typically written by a newer Iceberg version or a custom transform). visit() dispatches unrecognized transforms to unknown(sourceName, sourceId, transform, direction, nullOrder); the throwing default means the concrete visitor has no policy for such fields.

Source

Thrown at api/src/main/java/org/apache/iceberg/transforms/SortOrderVisitor.java:53

  T truncate(
      String sourceName, int sourceId, int width, SortDirection direction, NullOrder nullOrder);

  T year(String sourceName, int sourceId, SortDirection direction, NullOrder nullOrder);

  T month(String sourceName, int sourceId, SortDirection direction, NullOrder nullOrder);

  T day(String sourceName, int sourceId, SortDirection direction, NullOrder nullOrder);

  T hour(String sourceName, int sourceId, SortDirection direction, NullOrder nullOrder);

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

  /**
   * Visit the fields of a {@link SortOrder}.
   *
   * @param sortOrder a sort order to visit
   * @param visitor a sort order visitor
   * @param <R> return type of the visitor
   * @return a list of the result produced by visiting each sort field
   */
  @SuppressWarnings("checkstyle:CyclomaticComplexity")
  static <R> List<R> visit(SortOrder sortOrder, SortOrderVisitor<R> visitor) {
    Schema schema = sortOrder.schema();
    List<R> results = Lists.newArrayListWithExpectedSize(sortOrder.fields().size());

    for (SortField field : sortOrder.fields()) {
      String sourceName = schema.findColumnName(field.sourceId());

View on GitHub (pinned to 86d9c8fc54)

Solutions

Override unknown(String sourceName, int sourceId, String transform, SortDirection direction, NullOrder nullOrder) to map or explicitly reject unrecognized transforms
Upgrade the Iceberg version so the transform binds to a known class
Inspect sortOrder with order.fields() before visiting to detect unknown transform strings and handle them up front

Example fix

// before
default unknown() -> UnsupportedOperationException
// after
@Override
public String unknown(String sourceName, int sourceId, String transform,
    SortDirection direction, NullOrder nullOrder) {
  throw new IllegalArgumentException("Unsupported sort transform " + transform + "; upgrade Iceberg");
}

Defensive patterns

Strategy: validation

Validate before calling

boolean hasUnknownSortTransform(SortOrder order) {
  return order.fields().stream().anyMatch(f -> f.transform() instanceof UnknownTransform);
}
// check before SortOrderVisitor.visit(order, visitor)

Type guard

if (field.transform() instanceof UnknownTransform) {
  throw new IllegalStateException("Unsupported sort transform: " + field.transform());
}

Try / catch

try {
  SortOrderVisitor.visit(order, visitor);
} catch (UnsupportedOperationException e) {
  throw new IllegalStateException("Sort order uses unrecognized transform; upgrade Iceberg", e);
}

Prevention

Align reader/writer Iceberg versions to avoid UnknownTransform in sort orders
Override unknown(...) in SortOrderVisitor implementations to fail with the transform name
Pre-inspect order.fields() transform strings before metadata translation

When it happens

Trigger: SortOrderVisitor.visit(order, visitor) on a SortOrder whose field transform resolves to UnknownTransform — e.g. sort order created by a newer Iceberg version or vendor custom transform — without an unknown(...) override in the visitor.

Common situations: Rolling upgrades where an older reader translates a table's sort order written by a newer release; third-party catalogs with custom sort transforms; metadata translation tools (e.g. to other table formats) missing the unknown hook.

Related errors

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