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; it supports numeric, string, boolean, date, timestamp (incl. NTZ) and similar types. Any other type (maps, arrays, structs, binary, nested types) throws IllegalArgumentException.

Source

Thrown at spark/v4.2/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-ordering to supported columns (numeric, string, boolean, date, timestamp/NTZ).
2. Add a transform/expression producing a supported type, e.g. zOrder by a struct field or cast to string where meaningful.
3. Use regular sortOrder (rewriteSortOrder) for types ZOrdering doesn't support.

Example fix

// before
actions.rewriteDataFiles(table).zOrder("location.address").execute(); // struct unsupported
// after
actions.rewriteDataFiles(table).zOrder("location").execute(); // or a primitive column

Set<String> supported = Set.of("integer","long","short","byte","float","double","string","boolean","date","timestamp","timestamp_ntz","decimal"); List<Types.NestedField> cols = table.schema().columns(); // check each zOrder column's type is supported

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

try { rewrite.zOrder(col).execute(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("ZOrdering, the type is unsupported")) { /* fall back to sortCol or pick supported columns */ } else throw e; }

When it happens

Trigger: Calling SparkActions.zOrder(table, "col") / sort-zorder rewrite with a column whose Spark type is not in the supported set — e.g. struct, array, map, variant, or complex columns.

Common situations: Passing nested or complex columns (from schema evolution or misconfigured column names) to zOrder; assuming all primitive-adjacent types are supported.

Related errors

• Cannot use column %s of type %s in ZOrdering, the type is un
• Cannot use column %s of type %s in ZOrdering, the type is un
• Cannot convert type to SQL: %s
• Unsupported logical type:
• Unsupported type:

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