apache/kafka · error · IllegalArgumentException

More frequencies than buckets

Error message

More frequencies than buckets

What it means

Thrown by the Frequencies constructor when the number of Frequency metrics supplied exceeds the number of buckets. Each Frequency reports the count in the bucket centered on its centerValue, so you cannot meaningfully track more centered values than there are bins — at most one Frequency per bucket is the contract documented at line 81-83. The check enforces buckets >= frequencies.length.

Source

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

     * @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);
        for (Frequency frequency : frequencies) {
            final double center = frequency.centerValue();
            ms.add(new NamedMeasurable(frequency.name(), (config, now) -> frequency(config, now, center)));

View on GitHub (pinned to c31c9215e1)

Solutions

1. Raise buckets to at least the number of Frequency objects you pass.
2. Reduce the number of Frequency metrics so it fits within the bucket count.
3. Use Frequencies.forBooleanValues(...) for the common true/false case — it sets buckets=2 and supplies exactly two frequencies.

Example fix

// before
new Frequencies(2, 0.0, 10.0,
    new Frequency(low, 0.0), new Frequency(mid, 5.0), new Frequency(high, 10.0)); // 3 freqs, 2 buckets
// after
new Frequencies(3, 0.0, 10.0,
    new Frequency(low, 0.0), new Frequency(mid, 5.0), new Frequency(high, 10.0));

// Ensure the bucket count can hold every Frequency you pass:
if (frequencies == null) frequencies = new Frequency[0];
if (buckets < frequencies.length) {
    throw new IllegalArgumentException(
        "Need at least " + frequencies.length + " buckets for " + frequencies.length + " frequencies, got " + buckets);
}
return new Frequencies(buckets, min, max, frequencies);

When it happens

Trigger: Calling new Frequencies(buckets, min, max, freqs) with more Frequency entries than buckets — e.g. new Frequencies(2, 0, 1, f1, f2, f3). Happens when the bucket count is fixed (or computed independently) and does not account for how many distinct centerValues the caller wants to track.

Common situations: Boolean use that tracks 3+ outcomes but passes buckets=2; mismatch between a configured bucket count and a hard-coded list of Frequency metrics; refactoring that added a Frequency without raising the bucket count.

Related errors

• Must have at least 2 bins.
• Values less than 0.0 not accepted.
• The number of samples must be at least 1.
• For '{templateName}', runtime-defined metric tags do not mat
• Must specify at least one metric name

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