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

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.

Source

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

/**
 * A Spark function implementation for the Iceberg bucket transform.
 *
 * <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);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Pass exactly two arguments: system.bucket(numBuckets, value), e.g. SELECT system.bucket(8, id) FROM tbl
2. If you wanted a plain hash of a value, use a hash function instead of the bucket catalog function

Example fix

// before
spark.sql("SELECT system.bucket(id) FROM tbl")
// after
spark.sql("SELECT system.bucket(8, id) FROM tbl")

-- Ensure arity 2 before invoking
SELECT system.bucket(8, id) FROM tbl;

try {
  df = spark.sql("SELECT system.bucket(" + args + ") FROM tbl");
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("Wrong number of inputs")) { /* fix arity */ }
}

When it happens

Trigger: Calling system.bucket() with zero, one, or three-plus arguments in Spark SQL, e.g. system.bucket(8) or system.bucket(8, col, extra).

Common situations: 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.

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

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

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