apache/iceberg · error

Cannot bind unsupported transform: %s

Error message

Cannot bind unsupported transform: %s

What it means

UnknownTransform is a placeholder for a transform whose name the parser did not recognize (e.g. a transform added in a newer Iceberg spec version). Its bind() method always throws UnsupportedOperationException because an unknown transform cannot be compiled into a physical function for partition or sort expressions. The library throws this to fail fast rather than silently producing incorrect partitioning.

Source

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

  /**
   * Transforms a value to its corresponding partition value.
   *
   * @param value a source value
   * @return ∅
   * @throws UnsupportedOperationException Implementation is unknown
   * @deprecated will be removed in 2.0.0; use {@link #bind(Type)} instead
   */
  @Deprecated
  @Override
  public T apply(S value) {
    throw new UnsupportedOperationException(
        String.format("Cannot apply unsupported transform: %s", transform));
  }

  @Override
  public SerializableFunction<S, T> bind(Type type) {
    throw new UnsupportedOperationException(
        String.format("Cannot bind unsupported transform: %s", transform));
  }

  @Override
  public boolean canTransform(Type type) {
    // assume the transform function can be applied for any type
    return true;
  }

  @Override
  public Type getResultType(Type type) {
    // the actual result type is not known
    return Types.StringType.get();
  }

  @Override
  public UnboundPredicate<T> project(String name, BoundPredicate<S> predicate) {
    return null;

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Upgrade the Iceberg client to a version that supports the transform in the table metadata
2. Check the transform name string against supported names in Transforms (identity, year, month, day, hour, bucket[N], trunc[W])
3. Replace the partition spec field with a supported transform and migrate the table if the newer transform is not required

Example fix

// before
Transform t = Transforms.fromString("truncat"); // unknown
// after
Transform t = Transforms.fromString("trunc[10]"); // supported

Transform t = Transforms.fromString(name);
if (t instanceof UnknownTransform) { throw new IllegalArgumentException("Unsupported transform: " + name); }

boolean isKnown(Transform t) { return !(t instanceof UnknownTransform); }

try { fn = transform.bind(type); } catch (UnsupportedOperationException e) { throw new IllegalArgumentException("Transform unsupported for this client: " + e.getMessage()); }

When it happens

Trigger: Calling bind(Type) on a transform produced by Transforms.fromString/fromFunction with an unrecognized name, or building a PartitionSpec whose transform was parsed from metadata written by a newer Iceberg version.

Common situations: Reading table metadata written by a newer Iceberg release that defines a transform this client does not know; typo in transform name (e.g. 'truncat' instead of 'trunc'); custom transform functions not registered in Transforms.

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

• Identity transform is not supported
• Bucket transform is not supported
• Truncate transform is not supported
• Unsupported type for fromPartitionString: + type
• Can't retrieve values from an empty struct

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