apache/iceberg · error · java.lang.UnsupportedOperationException

Wrong number of inputs (expected numBuckets and value)

Error message

Wrong number of inputs (expected numBuckets and value)

What it means

BucketFunction implements Iceberg's bucket(size, value) SQL function for Spark. bind() validates the input signature: it requires exactly two arguments — numBuckets (integer type) and the value to bucket. Any call with a different argument count is rejected with UnsupportedOperationException before type checking.

Source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/functions/BucketFunction.java:71

 * <p>Example usage: {@code SELECT system.bucket(128, 'abc')}, which returns the bucket 122.
 *
 * <p>Note that for performance reasons, the given input number of buckets is not validated in the
 * implementations used in code-gen. The number of buckets must be positive to give meaningful
 * results.
 */
public class BucketFunction implements UnboundFunction {

  private static final int NUM_BUCKETS_ORDINAL = 0;
  private static final int VALUE_ORDINAL = 1;

  private static final Set<DataType> SUPPORTED_NUM_BUCKETS_TYPES =
      ImmutableSet.of(DataTypes.ByteType, DataTypes.ShortType, DataTypes.IntegerType);

  @Override
  @SuppressWarnings("checkstyle:CyclomaticComplexity")
  public BoundFunction bind(StructType inputType) {
    if (inputType.size() != 2) {
      throw new UnsupportedOperationException(
          "Wrong number of inputs (expected numBuckets and value)");
    }

    StructField numBucketsField = inputType.fields()[NUM_BUCKETS_ORDINAL];
    StructField valueField = inputType.fields()[VALUE_ORDINAL];

    if (!SUPPORTED_NUM_BUCKETS_TYPES.contains(numBucketsField.dataType())) {
      throw new UnsupportedOperationException(
          "Expected number of buckets to be tinyint, shortint or int");
    }

    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);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Call bucket with exactly two arguments: bucket(numBuckets, value), e.g. bucket(8, user_id).
2. If used in a partition spec, verify the transform syntax: PARTITIONED BY (bucket(8, user_id)).
3. Check for accidental extra arguments from expression composition or string interpolation in generated SQL.
4. Ensure the first argument is a literal integer (numBuckets) and only the second is the value column.

Example fix

// before
functions.call("bucket", lit(8)) // one argument
// after
functions.call("bucket", lit(8), col("user_id")) // numBuckets + value

if (args == null || args.length != 2) {
  throw new IllegalArgumentException("bucket() requires exactly 2 arguments: bucket(numBuckets, value)");
}

static boolean validBucketArgs(Expression[] args) {
  return args != null && args.length == 2 && args[0] instanceof Literal;
}

try {
  bound = bucketFn.bind(inputType);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("Wrong number of inputs")) {
    throw new AnalysisException("Use bucket(numBuckets, value) with exactly two arguments");
  } else throw e;
}

When it happens

Trigger: Invoking bucket() via Spark SQL or the catalog function interface with an argument count other than 2 — e.g. bucket(8) missing the value, bucket(8, col, extra), or SQL that mis-parses a nested call into multiple inputs.

Common situations: Hand-writing bucket() expressions for partition transforms; defining partitioned tables with a malformed transform spec; IDE/SQL autocompletion producing wrong arity; calling the function through engine code that flattens arguments incorrectly.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Wrong number of inputs (expected numBuckets and value)
• Cannot bind: ${name()} does not accept arguments
• Expected number of buckets to be tinyint, shortint or int
• Expected column to be date, tinyint, smallint, int, bigint,
• Expected value to be date or timestamp: ${valueType.catalogS

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