apache/iceberg · error · UnsupportedOperationException

Expected column to be date, tinyint, smallint, int, bigint,

Error message

Expected column to be date, tinyint, smallint, int, bigint, decimal, timestamp, string, or binary

What it means

The bucket function's value argument must be one of the types Iceberg's murmur3 bucket transform supports: date, tinyint, smallint, int, bigint, decimal, timestamp (and timestamp_ntz), string, or binary. Any other value type fails bind.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/functions/BucketFunction.java:95

    }

    DataType type = valueField.dataType();
    if (type instanceof DateType) {
      return new BucketInt(type);
    } else if (type instanceof ByteType
        || type instanceof ShortType
        || type instanceof IntegerType) {
      return new BucketInt(DataTypes.IntegerType);
    } else if (type instanceof LongType) {
      return new BucketLong(type);
    } else if (type instanceof TimestampType) {
      return new BucketLong(type);
    } else if (type instanceof TimestampNTZType) {
      return new BucketLong(type);
    } else if (type instanceof DecimalType) {
      return new BucketDecimal(type);
    } else if (type instanceof StringType) {
      return new BucketString();
    } else if (type instanceof BinaryType) {
      return new BucketBinary();
    } else {
      throw new UnsupportedOperationException(
          "Expected column to be date, tinyint, smallint, int, bigint, decimal, timestamp, string, or binary");
    }
  }

  @Override
  public String description() {
    return name()
        + "(numBuckets, col) - Call Iceberg's bucket transform\n"
        + "  numBuckets :: number of buckets to divide the rows into, e.g. bucket(100, 34) -> 79 (must be a tinyint, smallint, or int)\n"
        + "  col :: column to bucket (must be a date, integer, long, timestamp, decimal, string, or binary)";
  }

  @Override
  public String name() {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Cast the value to a supported type, e.g. CAST(double_col AS DECIMAL(38,10)) or CAST(col AS STRING) before bucketing
2. Pick a different partition/transform for unsupported types (e.g. truncate for strings, identity for booleans if needed)
3. Remove the column from the bucket expression and use a supported column instead

Example fix

// before
spark.sql("SELECT system.bucket(8, double_col) FROM tbl")
// after
spark.sql("SELECT system.bucket(8, CAST(double_col AS DECIMAL(38,10))) FROM tbl")

// Only bucket these types
Set<DataType> ok = Set.of(DateType, ByteType, ShortType, IntegerType, LongType,
    DecimalType, TimestampType, TimestampNTZType, StringType, BinaryType);
// check valueField.dataType() instanceof ok before calling system.bucket

boolean bucketable(DataType t) { return t instanceof DateType || t instanceof ByteType || t instanceof ShortType
  || t instanceof IntegerType || t instanceof LongType || t instanceof DecimalType
  || t instanceof TimestampType || t instanceof TimestampNTZType
  || t instanceof StringType || t instanceof BinaryType; }

When it happens

Trigger: Calling system.bucket(n, value) where value is e.g. float, double, boolean, array, struct, or map — types that have no bucket transform in Iceberg.

Common situations: Bucketing floating point columns (Iceberg spec does not define bucket for float/double); bucketing complex types; bucketing a timestamp column typed differently than expected after casts.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Wrong number of inputs (expected numBuckets and value)
• Expected number of buckets to be tinyint, shortint or int
• Cannot convert type to SQL: %s
• Cannot use column %s of type %s in ZOrdering, the type is un
• Unsupported logical type:

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