apache/iceberg · error · UnsupportedOperationException

HILBERT Rewrite Strategy not implemented for this framework

Error message

HILBERT Rewrite Strategy not implemented for this framework

What it means

RewriteDataFiles.hilbert(String...) selects the HILBERT curve rewrite strategy over the given columns. The interface default throws UnsupportedOperationException; invoking the stub means the current framework binding has not implemented the HILBERT strategy.

Solutions

Use an implementation that supports HILBERT (e.g. SparkActions' RewriteDataFiles)
Use zOrder(...) instead if the implementation supports it
Fall back to sort() or binpack() strategies available in the current implementation
Upgrade the integration module to a version implementing HILBERT

Example fix

// before
RewriteDataFiles.Result r = actions.rewriteDataFiles(table)
    .hilbert("x", "y")
    .execute();
// after
RewriteDataFiles.Result r = actions.rewriteDataFiles(table)
    .zOrder("x", "y") // if supported, or binpack()
    .execute();

Defensive patterns

Strategy: fallback

Try / catch

try {
  rewrite.hilbert(columns);
} catch (UnsupportedOperationException e) {
  rewrite.zOrder(columns); // or binpack()
}

Prevention

Verify HILBERT support before choosing it over Z-ORDER
Keep a strategy priority chain (hilbert -> zOrder -> sort -> binpack)
Use SparkActions for space-filling-curve strategies
Test compaction configuration on the actual engine version in use

When it happens

Trigger: Calling rewriteDataFiles().hilbert("colA", "colB") on an implementation that has not overridden the default hilbert method.

Common situations: Users choosing HILBERT over Z-ORDER for better locality on multi-dimensional data, but running against an engine binding (or older version) lacking the override; the failure happens when building the action.

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

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

Appendix: source

Thrown at api/src/main/java/org/apache/iceberg/actions/RewriteDataFiles.java:198

  /**
   * Choose Z-ORDER as a strategy for this rewrite operation with a specified list of columns to use
   *
   * @param columns Columns to be used to generate Z-Values
   * @return this for method chaining
   */
  default RewriteDataFiles zOrder(String... columns) {
    throw new UnsupportedOperationException(
        "Z-ORDER Rewrite Strategy not implemented for this framework");
  }

  /**
   * Choose HILBERT as a strategy for this rewrite operation with a specified list of columns to use
   *
   * @param columns Columns to be used to generate Hilbert values
   * @return this for method chaining
   */
  default RewriteDataFiles hilbert(String... columns) {
    throw new UnsupportedOperationException(
        "HILBERT Rewrite Strategy not implemented for this framework");
  }

  /**
   * A user provided filter for determining which files will be considered by the rewrite strategy.
   * This will be used in addition to whatever rules the rewrite strategy generates. For example
   * this would be used for providing a restriction to only run rewrite on a specific partition.
   *
   * @param expression An iceberg expression used to determine which files will be considered for
   *     rewriting
   * @return this for chaining
   */
  RewriteDataFiles filter(Expression expression);

  /**
   * A map of file group information to the results of rewriting that file group. If the results are
   * null then that particular file group failed. We should only have failed groups if partial
   * progress is enabled otherwise we will report a total failure for the job.

View on GitHub (pinned to 86d9c8fc54)