{"record":{"id":"9c1bcb90ad8c2851","repo":"apache/iceberg","slug":"expected-number-of-buckets-to-be-tinyint-shortint-9c1bcb","errorCode":null,"errorMessage":"Expected number of buckets to be tinyint, shortint or int","messagePattern":"Expected number of buckets to be tinyint, shortint or int","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/functions/BucketFunction.java","lineNumber":79,"sourceCode":"  private static final int NUM_BUCKETS_ORDINAL = 0;\n  private static final int VALUE_ORDINAL = 1;\n\n  private static final Set<DataType> SUPPORTED_NUM_BUCKETS_TYPES =\n      ImmutableSet.of(DataTypes.ByteType, DataTypes.ShortType, DataTypes.IntegerType);\n\n  @Override\n  @SuppressWarnings(\"checkstyle:CyclomaticComplexity\")\n  public BoundFunction bind(StructType inputType) {\n    if (inputType.size() != 2) {\n      throw new UnsupportedOperationException(\n          \"Wrong number of inputs (expected numBuckets and value)\");\n    }\n\n    StructField numBucketsField = inputType.fields()[NUM_BUCKETS_ORDINAL];\n    StructField valueField = inputType.fields()[VALUE_ORDINAL];\n\n    if (!SUPPORTED_NUM_BUCKETS_TYPES.contains(numBucketsField.dataType())) {\n      throw new UnsupportedOperationException(\n          \"Expected number of buckets to be tinyint, shortint or int\");\n    }\n\n    DataType type = valueField.dataType();\n    if (type instanceof DateType) {\n      return new BucketInt(type);\n    } else if (type instanceof ByteType\n        || type instanceof ShortType\n        || type instanceof IntegerType) {\n      return new BucketInt(DataTypes.IntegerType);\n    } else if (type instanceof LongType) {\n      return new BucketLong(type);\n    } else if (type instanceof TimestampType) {\n      return new BucketLong(type);\n    } else if (type instanceof TimestampNTZType) {\n      return new BucketLong(type);\n    } else if (type instanceof DecimalType) {\n      return new BucketDecimal(type);","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/functions/BucketFunction.java#L61-L97","documentation":"Type validation in BucketFunction.bind: the first argument (number of buckets) is not one of byte/tinyint, short/smallint or int — the accepted types for the bucket count. The %s names the offending field; cast the bucket count to int before calling system.bucket.","triggerScenarios":"Invoking system.bucket(...) with numBuckets supplied as a long, decimal, string literal, or a non-integral column type.","commonSituations":"Passing a long constant like 8L in Scala/Java API; numBuckets read from a bigint column; schema evolution changing the bucket-count column type.","solutions":["Use a tinyint/short/int value for numBuckets, e.g. system.bucket(8, id) with an int literal","Cast the numBuckets column: system.bucket(CAST(n AS INT), id)","Avoid passing bigint columns as bucket counts; compute with int"],"exampleFix":"// before\nSELECT system.bucket(CAST(8 AS BIGINT), id) FROM t;\n// after\nSELECT system.bucket(8, id) FROM t;","handlingStrategy":"type-guard","validationCode":"if (numBuckets.dataType() != IntegerType && numBuckets.dataType() != ShortType && numBuckets.dataType() != ByteType) {\n  throw new IllegalArgumentException(\"numBuckets must be int/short/tinyint\");\n}","typeGuard":"boolean isIntLike(DataType t) {\n  return t instanceof ByteType || t instanceof ShortType || t instanceof IntegerType;\n}","tryCatchPattern":"try {\n  bound = bucketFn.bind(inputType);\n} catch (UnsupportedOperationException e) {\n  throw new IllegalArgumentException(\"Cast numBuckets to INT\", e);\n}","preventionTips":["Use plain int literals for bucket counts (e.g. 8, not 8L)","Avoid binding bucket counts from bigint columns","Validate argument types before building bucketed queries"],"tags":["spark","sql-function","bucket-transform","type-mismatch"],"backgroundTag":"invalid-argument-value","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"}