apache/iceberg · error · IllegalArgumentException

Cannot use column %s of type %s in ZOrdering, the type is un

Error message

Cannot use column %s of type %s in ZOrdering, the type is unsupported

What it means

SparkZOrderUDF.sortedLexicographically converts a Spark column to lexicographically ordered bytes for Z-Order sorting, but only supports numeric, timestamp, date, NTZ and similar types. A column of any other type (e.g. string handled elsewhere, or struct/map/array/binary) reaches the else branch and throws IllegalArgumentException.

Source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/actions/SparkZOrderUDF.java:343

      return longToOrderedBytesUDF().apply(column);
    } else if (type instanceof FloatType) {
      return floatToOrderedBytesUDF().apply(column);
    } else if (type instanceof DoubleType) {
      return doubleToOrderedBytesUDF().apply(column);
    } else if (type instanceof StringType) {
      return stringToOrderedBytesUDF().apply(column);
    } else if (type instanceof BinaryType) {
      return bytesTruncateUDF().apply(column);
    } else if (type instanceof BooleanType) {
      return booleanToOrderedBytesUDF().apply(column);
    } else if (type instanceof TimestampType) {
      return longToOrderedBytesUDF().apply(column.cast(DataTypes.LongType));
    } else if (type instanceof TimestampNTZType) {
      return timestampNtzToOrderedBytesUDF().apply(column);
    } else if (type instanceof DateType) {
      return longToOrderedBytesUDF().apply(functions.unix_date(column).cast(DataTypes.LongType));
    } else {
      throw new IllegalArgumentException(
          String.format(
              "Cannot use column %s of type %s in ZOrdering, the type is unsupported",
              column, type));
    }
  }

  private void increaseOutputSize(int bytes) {
    totalOutputBytes = Math.min(totalOutputBytes + bytes, maxOutputSize);
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Restrict Z-Order columns to supported types (numeric, timestamp, timestamp_ntz, date, string, boolean, etc.)
2. Cast or derive an orderable key column first (e.g. date_trunc on a timestamp, element access on an array)
3. Use a different sort strategy (sort_order) for unsupported column types
4. Check the column's dataType with table.schema()/df.schema() before running the rewrite

Example fix

// before
SparkActions.get(table).rewriteDataFiles()
    .sort(SortStrategy.zOrder("complex_col")).execute();
// after: use an orderable derived key or sort_order instead
SparkActions.get(table).rewriteDataFiles()
    .sort(SortStrategy.sortOrder(Expressions.asc("complex_col"))).execute();

Schema schema = table.schema();
for (String col : zOrderCols) {
  Type t = schema.findType(col);
  Preconditions.checkArgument(
      t.typeId() == Type.TypeID.LONG || t.typeId() == Type.TypeID.DOUBLE
          || t.typeId() == Type.TypeID.DATE || t.typeId() == Type.TypeID.TIMESTAMP,
      "Unsupported ZOrder type for " + col);
}

boolean zOrderable(DataType t) { return t instanceof NumericType || t instanceof DateType || t instanceof TimestampType || t instanceof TimestampNTZType || t instanceof StringType; }

try { rewrite.sort(SortStrategy.zOrder(cols)).execute(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("ZOrdering")) { /* switch column or sort strategy */ } else { throw e; } }

When it happens

Trigger: Calling zOrder_COLS / SparkZOrderUDF with a column whose Spark DataType is not one of the supported types — e.g. Z-Ordering by a nested, binary, or unsupported complex-typed column.

Common situations: Passing struct/map/array or other complex columns to sortCol in rewriteDataFiles with zOrder sort strategy; typo resolving to a wrong-typed column; variant-typed columns on newer tables.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Cannot mix identity sort columns and a Zorder sort expressio
• Table does not implement %s: %s (%s)
• Cannot commit rewrite because of a ValidationException or Co
• %s is true but %d rewrite commits failed. This is more than
• Cannot use column %s of type %s in ZOrdering, the type is un

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