apache/iceberg · error · UnsupportedOperationException

Transform is not supported: ${transform}

Error message

Transform is not supported: ${transform}

What it means

toIcebergTerm converts Spark sort/ordering expressions and transforms into Iceberg terms. Within a SortOrder expression, recognized transforms include identity, bucket, truncate, years/months/days/hours, and zorder; any other transform hits the default branch and throws this UnsupportedOperationException.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java:404

          return org.apache.iceberg.expressions.Expressions.month(colName);
        case "date":
        case "day":
        case "days":
          return org.apache.iceberg.expressions.Expressions.day(colName);
        case "date_hour":
        case "hour":
        case "hours":
          return org.apache.iceberg.expressions.Expressions.hour(colName);
        case "truncate":
          return org.apache.iceberg.expressions.Expressions.truncate(colName, findWidth(transform));
        case "zorder":
          return new Zorder(
              Stream.of(transform.references())
                  .map(ref -> DOT.join(ref.fieldNames()))
                  .map(org.apache.iceberg.expressions.Expressions::ref)
                  .collect(Collectors.toList()));
        default:
          throw new UnsupportedOperationException("Transform is not supported: " + transform);
      }

    } else if (expr instanceof NamedReference) {
      NamedReference ref = (NamedReference) expr;
      return org.apache.iceberg.expressions.Expressions.ref(DOT.join(ref.fieldNames()));

    } else {
      throw new UnsupportedOperationException("Cannot convert unknown expression: " + expr);
    }
  }

  /**
   * Converts Spark transforms into a {@link PartitionSpec}.
   *
   * @param schema the table schema
   * @param partitioning Spark Transforms
   * @return a PartitionSpec
   */

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Restrict sort/cluster transforms to identity, bucket, truncate, years, months, days, hours, or zorder
2. Apply unsupported transforms upstream before writing data
3. Upgrade Iceberg to a version that maps the desired transform

Example fix

// before
SORTED BY (month(ts))
// after
SORTED BY (days(ts))

boolean supportedSortTransform(Transform t) { return Set.of("identity","bucket","truncate","years","months","days","hours").contains(t.name().toLowerCase(Locale.ROOT)); }

boolean isTransformOrRef(Expression e) { return e instanceof Transform || e instanceof NamedReference; }

try { Spark3Util.toIcebergTerm(expr); } catch (UnsupportedOperationException e) { if (e.getMessage().startsWith("Transform is not supported")) { /* replace with a supported transform */ } else throw e; }

When it happens

Trigger: Spark ORDER BY / SORTED BY / clustering requests whose transform expression is one Iceberg doesn't support — e.g. arbitrary SQL functions wrapped around a column in a sort specification.

Common situations: Using Iceberg's z-order/cluster DDL extensions with transforms beyond the supported set; engine plugins generating custom transforms.

Related errors

• Transform is not supported:
• Unable to parse sortOrder: %s
• Cannot add column %s since setting default values in Spark i
• Cannot convert unknown expression: ${expr}
• Cannot find width for transform: %s

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