apache/iceberg · error · java.lang.UnsupportedOperationException

Cannot write using unsupported transforms: %s

Error message

Cannot write using unsupported transforms: %s

What it means

When planning a Spark write to an Iceberg table, the partition spec is validated to ensure every partition field uses a transform Spark can evaluate. If the spec contains an UnknownTransform (a transform from a newer/newer-unknown spec version or custom catalog), writes cannot route rows correctly and fail with UnsupportedOperationException listing the offending transforms.

Source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/SparkUtil.java:100

  private SparkUtil() {}

  /**
   * Check whether the partition transforms in a spec can be used to write data.
   *
   * @param spec a PartitionSpec
   * @throws UnsupportedOperationException if the spec contains unknown partition transforms
   */
  public static void validatePartitionTransforms(PartitionSpec spec) {
    if (spec.fields().stream().anyMatch(field -> field.transform() instanceof UnknownTransform)) {
      String unsupported =
          spec.fields().stream()
              .map(PartitionField::transform)
              .filter(transform -> transform instanceof UnknownTransform)
              .map(Transform::toString)
              .collect(Collectors.joining(", "));

      throw new UnsupportedOperationException(
          String.format("Cannot write using unsupported transforms: %s", unsupported));
    }
  }

  /**
   * A modified version of Spark's LookupCatalog.CatalogAndIdentifier.unapply Attempts to find the
   * catalog and identifier a multipart identifier represents
   *
   * @param nameParts Multipart identifier representing a table
   * @return The CatalogPlugin and Identifier for the table
   */
  public static <C, T> Pair<C, T> catalogAndIdentifier(
      List<String> nameParts,
      Function<String, C> catalogProvider,
      BiFunction<String[], String, T> identiferProvider,
      C currentCatalog,
      String[] currentNamespace) {
    Preconditions.checkArgument(

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Upgrade the Iceberg Spark runtime to a version that understands the table's transforms (align reader/writer versions)
2. Remove or rewrite the partition spec to use supported transforms (identity, bucket, truncate, years/months/days/hours) via ReplacePartitionSpec/update location
3. Avoid writing to that table from this Spark version; produce data through the engine that created the spec

Example fix

// before
// built with newer iceberg-spark runtime, table has unknown transform
spark.writeTo("catalog.db.table").append();
// after
// upgrade dependency to matching version
// build.gradle: implementation 'org.apache.iceberg:iceberg-spark-runtime-4.2_2.13:<matching-version>'

for (PartitionField field : table.spec().fields()) {
  if (field.transform() instanceof UnknownTransform) {
    throw new IllegalStateException("Unsupported partition transform: " + field.transform());
  }
}

try { df.writeTo("catalog.db.table").append(); } catch (UnsupportedOperationException e) { if (e.getMessage().startsWith("Cannot write using unsupported transforms")) { /* upgrade runtime or rewrite spec */ } else throw e; }

When it happens

Trigger: Writing to an Iceberg table whose partition spec was created by a newer Iceberg version (or another engine) using transforms this Spark writer does not recognize; the table's spec.fields() contains a PartitionField whose transform is UnknownTransform, checked via SparkUtil.validatePartitionTransforms during write planning.

Common situations: Reader/writer version skew: table created with a newer Iceberg release or with engine-specific partitioning (e.g. new bucket/day variants), then consumed by an older Spark runtime; cross-catalog table sharing where one side upgraded.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Invalid transform argument
• Unknown transform %s is not supported
• Cannot bind unsupported transform: %s
• Cannot update partition spec with unknown transform:
• Unsupported transform: ${transform}

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