apache/iceberg · error · UnsupportedOperationException

Wrong number of inputs (expected numBuckets and value)

Error message

Wrong number of inputs (expected numBuckets and value)

What it means

Arity validation in BucketFunction.bind: system.bucket was invoked with an input schema whose size is not exactly 2 (numBuckets and value). It fires at function binding, before execution; pass the bucket count as the first argument and the value as the second.

Source

Thrown at spark/v4.1/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. Pass exactly two arguments: bucket(numBuckets, expr), e.g. system.bucket(8, id)
2. Check your SQL/code that generates the call to ensure both numBuckets and value are supplied
3. For varying bucket counts, generate separate calls rather than extra arguments

Example fix

// before
SELECT system.bucket(id) FROM t;            -- 1 arg
// after
SELECT system.bucket(8, id) FROM t;         -- numBuckets + value

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

try {
  bound = fn.bind(structType);
} catch (UnsupportedOperationException e) {
  throw new IllegalArgumentException("Fix bucket() call arity: bucket(numBuckets, value)", e);
}

When it happens

Trigger: Calling the SQL expression system.bucket(...) with one, three, or zero arguments instead of exactly two (numBuckets, value).

Common situations: Mistakenly passing only the value (forgetting numBuckets); passing extra column arguments; SQL generation tools emitting wrong arity.

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 width and value)
• Wrong number of inputs (expected value)
• Expected number of buckets to be tinyint, shortint or int
• Expected column to be date, tinyint, smallint, int, bigint,
• Cannot bind: %s does not accept arguments

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