apache/kafka · error · IllegalArgumentException

Must have at least 2 bins.

Error message

Must have at least 2 bins.

What it means

Thrown by `Histogram.ConstantBinScheme`'s constructor when the requested bin count is less than 2. The scheme needs at least two bins because `bucketWidth = (max - min) / bins` must produce a positive, finite interval and because the value() percentile lookup iterates `hist.length - 1` bins. With one or zero bins the histogram collapses and percentile/frequency math becomes meaningless, so Kafka rejects the configuration at construction.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/metrics/stats/Histogram.java:136

     * and the number of bins.
     */
    public static class ConstantBinScheme implements BinScheme {
        private static final int MIN_BIN_NUMBER = 0;
        private final double min;
        private final int bins;
        private final double bucketWidth;
        private final int maxBinNumber;

        /**
         * Create a bin scheme with the specified number of bins that all have the same width.
         *
         * @param bins the number of bins; must be at least 2
         * @param min the minimum value to be counted in the bins
         * @param max the maximum value to be counted in the bins
         */
        public ConstantBinScheme(int bins, double min, double max) {
            if (bins < 2)
                throw new IllegalArgumentException("Must have at least 2 bins.");
            this.min = min;
            this.bins = bins;
            this.bucketWidth = (max - min) / bins;
            this.maxBinNumber = bins - 1;
        }

        public int bins() {
            return this.bins;
        }

        public double fromBin(int b) {
            if (b < MIN_BIN_NUMBER) {
                return Float.NEGATIVE_INFINITY;
            }
            if (b > maxBinNumber) {
                return Float.POSITIVE_INFINITY;
            }
            return min + b * bucketWidth;

View on GitHub (pinned to c31c9215e1)

Solutions

1. Ensure `sizeInBytes` passed to Percentiles is at least 8 (yields 2 buckets); typically use 4096+ for meaningful percentiles.
2. If constructing ConstantBinScheme directly, pass `bins >= 2`.
3. Validate the computed bucket count in a unit test before creating the metric.

Example fix

// before
new Percentiles(4, 100.0, BucketSizing.CONSTANT, p50, p99); // 4/4 = 1 bin

// after
new Percentiles(4096, 100.0, BucketSizing.CONSTANT, p50, p99); // 1024 bins

if (bins < 2) {
    throw new IllegalArgumentException("ConstantBinScheme requires bins >= 2, got " + bins);
}
new Histogram.ConstantBinScheme(bins, min, max);

try {
    binScheme = new Histogram.ConstantBinScheme(bins, min, max);
} catch (IllegalArgumentException e) {
    // "Must have at least 2 bins."
    bins = Math.max(bins, 2);
    binScheme = new Histogram.ConstantBinScheme(bins, min, max);
}

When it happens

Trigger: Calling `new ConstantBinScheme(bins, min, max)` with `bins < 2`. Most commonly hit indirectly when `Percentiles` computes `buckets = sizeInBytes / 4` and `sizeInBytes` is less than 8 (so buckets resolves to 0 or 1), then constructs `new ConstantBinScheme(buckets, min, max)`.

Common situations: Passing a very small `sizeInBytes` to a `Percentiles` metric. Copying a metric configuration and trimming the bucket budget too aggressively. Misreading `sizeInBytes` as the number of buckets rather than bytes (4 bytes per bucket).

Related errors

• Values less than 0.0 not accepted.
• Linear bucket sizing requires min to be 0.0.
• The frequency centered at '{centerValue}' is not within the
• The maximum value {max} must be greater than the minimum val
• Must be at least 1 bucket

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