{"record":{"id":"23d81232bb3143bd","repo":"apache/iceberg","slug":"wrong-number-of-inputs-expected-numbuckets-and-va","errorCode":null,"errorMessage":"Wrong number of inputs (expected numBuckets and value)","messagePattern":"Wrong number of inputs \\(expected numBuckets and value\\)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/functions/BucketFunction.java","lineNumber":63,"sourceCode":"\n/**\n * A Spark function implementation for the Iceberg bucket transform.\n *\n * <p>Example usage: {@code SELECT system.bucket(128, 'abc')}, which returns the bucket 122.\n *\n * <p>Note that for performance reasons, the given input number of buckets is not validated in the\n * implementations used in code-gen. The number of buckets must be positive to give meaningful\n * results.\n */\npublic class BucketFunction implements UnboundFunction {\n\n  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);","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/functions/BucketFunction.java#L45-L81","documentation":"The SQL bucket(n, expr) function (Spark catalog function backed by Iceberg) requires exactly two arguments: the number of buckets and the value. Binding a call with any other arity throws UnsupportedOperationException.","triggerScenarios":"Calling system.bucket() with zero, one, or three-plus arguments in Spark SQL, e.g. system.bucket(8) or system.bucket(8, col, extra).","commonSituations":"Hand-written SQL that omits the bucket count (remembering only the hash-expr style from other engines) or passes extra arguments; mistakenly calling it like Murmur3 hash UDFs with different signatures.","solutions":["Pass exactly two arguments: system.bucket(numBuckets, value), e.g. SELECT system.bucket(8, id) FROM tbl","If you wanted a plain hash of a value, use a hash function instead of the bucket catalog function"],"exampleFix":"// before\nspark.sql(\"SELECT system.bucket(id) FROM tbl\")\n// after\nspark.sql(\"SELECT system.bucket(8, id) FROM tbl\")","handlingStrategy":"validation","validationCode":"-- Ensure arity 2 before invoking\nSELECT system.bucket(8, id) FROM tbl;","typeGuard":null,"tryCatchPattern":"try {\n  df = spark.sql(\"SELECT system.bucket(\" + args + \") FROM tbl\");\n} catch (UnsupportedOperationException e) {\n  if (e.getMessage().contains(\"Wrong number of inputs\")) { /* fix arity */ }\n}","preventionTips":["Always pass exactly two args: numBuckets then value","Remember bucket() is not a plain hash UDF; it needs the bucket count","Validate SQL templates that interpolate function arguments"],"tags":["spark","sql-functions","bucketing","argument-count"],"backgroundTag":"missing-required-argument","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}