{"record":{"id":"c805719ff108df5c","repo":"apache/iceberg","slug":"cannot-use-column-s-of-type-s-in-zordering-the-c80571","errorCode":null,"errorMessage":"Cannot use column %s of type %s in ZOrdering, the type is unsupported","messagePattern":"Cannot use column (.+?) of type (.+?) in ZOrdering, the type is unsupported","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/actions/SparkZOrderUDF.java","lineNumber":343,"sourceCode":"      return longToOrderedBytesUDF().apply(column);\n    } else if (type instanceof FloatType) {\n      return floatToOrderedBytesUDF().apply(column);\n    } else if (type instanceof DoubleType) {\n      return doubleToOrderedBytesUDF().apply(column);\n    } else if (type instanceof StringType) {\n      return stringToOrderedBytesUDF().apply(column);\n    } else if (type instanceof BinaryType) {\n      return bytesTruncateUDF().apply(column);\n    } else if (type instanceof BooleanType) {\n      return booleanToOrderedBytesUDF().apply(column);\n    } else if (type instanceof TimestampType) {\n      return longToOrderedBytesUDF().apply(column.cast(DataTypes.LongType));\n    } else if (type instanceof TimestampNTZType) {\n      return timestampNtzToOrderedBytesUDF().apply(column);\n    } else if (type instanceof DateType) {\n      return longToOrderedBytesUDF().apply(functions.unix_date(column).cast(DataTypes.LongType));\n    } else {\n      throw new IllegalArgumentException(\n          String.format(\n              \"Cannot use column %s of type %s in ZOrdering, the type is unsupported\",\n              column, type));\n    }\n  }\n\n  private void increaseOutputSize(int bytes) {\n    totalOutputBytes = Math.min(totalOutputBytes + bytes, maxOutputSize);\n  }\n}\n","sourceCodeStart":325,"sourceCodeEnd":354,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/actions/SparkZOrderUDF.java#L325-L354","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Restrict Z-Order columns to supported types (numeric, timestamp, timestamp_ntz, date, string, boolean, etc.)","Cast or derive an orderable key column first (e.g. date_trunc on a timestamp, element access on an array)","Use a different sort strategy (sort_order) for unsupported column types","Check the column's dataType with table.schema()/df.schema() before running the rewrite"],"exampleFix":"// before\nSparkActions.get(table).rewriteDataFiles()\n    .sort(SortStrategy.zOrder(\"complex_col\")).execute();\n// after: use an orderable derived key or sort_order instead\nSparkActions.get(table).rewriteDataFiles()\n    .sort(SortStrategy.sortOrder(Expressions.asc(\"complex_col\"))).execute();","handlingStrategy":"type-guard","validationCode":"Schema schema = table.schema();\nfor (String col : zOrderCols) {\n  Type t = schema.findType(col);\n  Preconditions.checkArgument(\n      t.typeId() == Type.TypeID.LONG || t.typeId() == Type.TypeID.DOUBLE\n          || t.typeId() == Type.TypeID.DATE || t.typeId() == Type.TypeID.TIMESTAMP,\n      \"Unsupported ZOrder type for \" + col);\n}","typeGuard":"boolean zOrderable(DataType t) { return t instanceof NumericType || t instanceof DateType || t instanceof TimestampType || t instanceof TimestampNTZType || t instanceof StringType; }","tryCatchPattern":"try { rewrite.sort(SortStrategy.zOrder(cols)).execute(); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"ZOrdering\")) { /* switch column or sort strategy */ } else { throw e; } }","preventionTips":["Only Z-Order on primitive orderable columns (numeric, date, timestamp, string, boolean)","Derive orderable keys for complex columns before Z-Ordering","Validate column types against table.schema() before launching the rewrite"],"tags":["spark","zorder","type-mismatch","rewrite-data-files"],"backgroundTag":"type-mismatch","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}