What causes "Must be at least 1 bucket" in apache/kafka?

Pass buckets >= 1 (preferably >= 2 so the ConstantBinScheme width math does not divide by zero).

apache/kafka · error · IllegalArgumentException

Must be at least 1 bucket

Error message

Must be at least 1 bucket

What it means

Thrown by the Frequencies constructor when the buckets argument is less than 1. Frequencies needs at least one bin in its ConstantBinScheme to record any values; zero or negative buckets would produce a degenerate histogram that cannot classify samples. Note also that with buckets == 1 the bucket-width math at line 106 divides by (buckets-1) == 0 — callers should generally use at least 2 buckets.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/metrics/stats/Frequencies.java:94

     * where the buckets are centered around the minimum, maximum, and intermediate values.
     *
     * @param buckets     the number of buckets; must be at least 1
     * @param min         the minimum value to be captured
     * @param max         the maximum value to be captured
     * @param frequencies the list of {@link Frequency} metrics, which at most should be one per bucket centered
     *                    on the bucket's value, though not every bucket need to correspond to a metric if the
     *                    value is not needed
     * @throws IllegalArgumentException if any of the {@link Frequency} objects do not have a
     *                                  {@link Frequency#centerValue() center value} within the specified range
     */
    public Frequencies(int buckets, double min, double max, Frequency... frequencies) {
        super(0.0); // initial value is unused by this implementation
        if (max < min) {
            throw new IllegalArgumentException("The maximum value " + max
                                                       + " must be greater than the minimum value " + min);
        }
        if (buckets < 1) {
            throw new IllegalArgumentException("Must be at least 1 bucket");
        }
        if (buckets < frequencies.length) {
            throw new IllegalArgumentException("More frequencies than buckets");
        }
        this.frequencies = frequencies;
        for (Frequency freq : frequencies) {
            if (min > freq.centerValue() || max < freq.centerValue()) {
                throw new IllegalArgumentException("The frequency centered at '" + freq.centerValue()
                                                           + "' is not within the range [" + min + "," + max + "]");
            }
        }
        double halfBucketWidth = (max - min) / (buckets - 1) / 2.0;
        this.binScheme = new ConstantBinScheme(buckets, min - halfBucketWidth, max + halfBucketWidth);
    }

    @Override
    public List<NamedMeasurable> stats() {
        List<NamedMeasurable> ms = new ArrayList<>(frequencies.length);

View on GitHub (pinned to c31c9215e1)

Solutions

Pass buckets >= 1 (preferably >= 2 so the ConstantBinScheme width math does not divide by zero).
Default and validate any config-driven bucket count: clamp to a minimum of 2 and reject non-positive values upstream with a clearer error.
For boolean distributions use Frequencies.forBooleanValues(...) which fixes buckets=2.

Example fix

// before
new Frequencies(0, 0.0, 1.0, freqs); // throws
// after
new Frequencies(2, 0.0, 1.0, freqs);

Defensive patterns

Strategy: validation

Validate before calling

// Pre-validate bucket count:
if (buckets < 1) {
    throw new IllegalArgumentException("buckets must be >= 1, got " + buckets);
}
return new Frequencies(buckets, min, max, frequencies);

Prevention

Always pass buckets >= 1; a single bucket is the minimum useful configuration.
Validate buckets against your frequencies array length too: buckets must be >= frequencies.length.
Surface this as a configuration error to operators rather than letting it surface as a runtime exception during metric registration.

When it happens

Trigger: Calling new Frequencies(buckets, ...) with buckets <= 0, typically because the value was read from a config that defaulted to 0 or was computed from a count that turned out to be zero.

Common situations: Config-driven bucket counts where the property was unset or mistyped; computing buckets from a dynamic size (e.g. distinct value count) that returned 0; passing a negative constant by mistake.

Related errors

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/1713b0da3584c491.json. Report an issue: GitHub.