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 sorts columns by converting values to order-preserving byte arrays. The typeToOrderedBytesUDF helper only supports Iceberg's Z-order compatible types (numeric, temporal, string, etc.); any other Spark DataType is rejected with IllegalArgumentException because lexicographic byte ordering would not preserve value ordering for that type.

Source

Thrown at spark/v4.1/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. Remove the unsupported column from the zorder column list and keep only primitive columns
2. Cast or extract a primitive value (e.g. an element or hash of the complex value) into a supported column before zordering
3. Check the table property sort-order / rewrite options for the exact column list
4. Refer to SparkZOrderUDF.typeToOrderedBytesUDF for the supported type list

Example fix

// before
SparkActions.get().rewriteDataFiles(table).sort(SortOrderBuilder.builderFor(table).zOrder("location MAP<STRING,STRING>").build())
// after
SparkActions.get().rewriteDataFiles(table).sort(SortOrderBuilder.builderFor(table).zOrder("country").build())

for (String col : zorderCols) {
  DataType t = spark.table(table.name()).schema().apply(col).dataType();
  if (!(t instanceof NumericType) && !(t instanceof StringType) && !(t instanceof DateType)
      && !(t instanceof TimestampType) && !(t instanceof TimestampNTZType)) {
    throw new IllegalArgumentException("Unsupported zorder column type: " + col + " -> " + t);
  }
}

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

try {
  rewrite.sort(SortOrderBuilder.builderFor(table).zOrder(cols).build()).execute();
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("ZOrdering")) { /* drop or remap the offending column */ }
  else throw e;
}

When it happens

Trigger: Calling the zorder sort_order rewrite (RewriteDataFilesSparkAction with sort strategy 'zorder') including a column whose Spark type is not in the supported set, e.g. a MAP, ARRAY, STRUCT, or BINARY column.

Common situations: Configuring zorder on nested/complex columns; typos that resolve to a complex type; tables with variant or binary columns included in zorder_cols property.

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
• Ignoring '{}' as such values are constant within a partition
• Cannot convert type to SQL: %s
• Unsupported logical type:

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