apache/iceberg · error · IllegalArgumentException

Cannot mix Zorder and Hilbert sort expressions: ${sortOrderS

Error message

Cannot mix Zorder and Hilbert sort expressions: ${sortOrderString}

What it means

RewriteDataFilesProcedure's sort_order option accepts either Z-order terms, Hilbert terms, or plain identity columns — not a mix of Z-order and Hilbert in the same expression. parseSortOrder throws this IllegalArgumentException when both zorder(...) and hilbert(...) appear in the sort_order string.

Source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/procedures/RewriteDataFilesProcedure.java:205

  private void parseSortOrder(
      String sortOrderString,
      List<Zorder> zOrderTerms,
      List<Hilbert> hilbertTerms,
      List<ExtendedParser.RawOrderField> sortOrderFields) {
    ExtendedParser.parseSortOrder(spark(), sortOrderString)
        .forEach(
            field -> {
              if (field.term() instanceof Zorder) {
                zOrderTerms.add((Zorder) field.term());
              } else if (field.term() instanceof Hilbert) {
                hilbertTerms.add((Hilbert) field.term());
              } else {
                sortOrderFields.add(field);
              }
            });

    if (!zOrderTerms.isEmpty() && !hilbertTerms.isEmpty()) {
      throw new IllegalArgumentException(
          "Cannot mix Zorder and Hilbert sort expressions: " + sortOrderString);
    }

    if ((!zOrderTerms.isEmpty() || !hilbertTerms.isEmpty()) && !sortOrderFields.isEmpty()) {
      throw new IllegalArgumentException(
          "Cannot mix identity sort columns and a Zorder or Hilbert sort expression: "
              + sortOrderString);
    }
  }

  private RewriteDataFilesSparkAction applySortStrategy(
      RewriteDataFilesSparkAction action,
      List<Zorder> zOrderTerms,
      List<Hilbert> hilbertTerms,
      List<ExtendedParser.RawOrderField> sortOrderFields,
      Schema schema) {
    if (!zOrderTerms.isEmpty()) {
      String[] columnNames =

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Choose one spatial ordering scheme: use only zorder(...) terms or only hilbert(...) terms.
2. Remove the unwanted zorder/hilbert term from the sort_order option.
3. If both orderings are needed, run rewrite_data_files twice in separate passes.

Example fix

// before
call rewrite_data_files(table => 'db.t', sort_order => 'zorder(a,b) hilbert(c,d)')
// after
call rewrite_data_files(table => 'db.t', sort_order => 'hilbert(a,b,c,d)')

val hasZ = sortOrder.contains("zorder(")
val hasH = sortOrder.contains("hilbert(")
require(!(hasZ && hasH), "cannot mix zorder and hilbert")

When it happens

Trigger: Calling rewrite_data_files with sort_order => 'zorder(a, b), hilbert(c, d)' or an expression combining both functions.

Common situations: Combining sort expressions from different examples; evolving configs where one term was switched to hilbert but the other zorder term was left in place.

Related errors

• Cannot mix identity sort columns and a Zorder sort expressio
• Cannot mix identity sort columns and a Zorder or Hilbert sor
• Unable to parse sortOrder: %s
• Transform is not supported: ${transform}
• Cannot specify the 'sort-order' because it's a reserved tabl

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