apache/kafka · error · IllegalArgumentException

Linear bucket sizing requires min to be 0.0.

Error message

Linear bucket sizing requires min to be 0.0.

What it means

Thrown by the Percentiles constructor when `BucketSizing.LINEAR` is selected but `min` is not exactly 0.0. LinearBinScheme is mathematically defined only for a domain starting at zero (its `toBin` inversion uses `sqrt(1 + 8x/scale)` assuming x >= 0 from 0). Allowing a non-zero min would shift the recorded values out of the scheme's valid range and produce wrong percentiles, so Kafka rejects it.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/metrics/stats/Percentiles.java:64

    private final BinScheme binScheme;
    private final double min;
    private final double max;

    public Percentiles(int sizeInBytes, double max, BucketSizing bucketing, Percentile... percentiles) {
        this(sizeInBytes, 0.0, max, bucketing, percentiles);
    }

    public Percentiles(int sizeInBytes, double min, double max, BucketSizing bucketing, Percentile... percentiles) {
        super(0.0);
        this.percentiles = percentiles;
        this.buckets = sizeInBytes / 4;
        this.min = min;
        this.max = max;
        if (bucketing == BucketSizing.CONSTANT) {
            this.binScheme = new ConstantBinScheme(buckets, min, max);
        } else if (bucketing == BucketSizing.LINEAR) {
            if (min != 0.0d)
                throw new IllegalArgumentException("Linear bucket sizing requires min to be 0.0.");
            this.binScheme = new LinearBinScheme(buckets, max);
        } else {
            throw new IllegalArgumentException("Unknown bucket type: " + bucketing);
        }
    }

    @Override
    public List<NamedMeasurable> stats() {
        List<NamedMeasurable> ms = new ArrayList<>(this.percentiles.length);
        for (Percentile percentile : this.percentiles) {
            final double pct = percentile.percentile();
            ms.add(new NamedMeasurable(
                percentile.name(),
                (config, now) -> value(config, now, pct / 100.0))
            );
        }
        return ms;
    }

View on GitHub (pinned to c31c9215e1)

Solutions

1. Set `min = 0.0` when using BucketSizing.LINEAR (use the 4-arg constructor which does this for you).
2. If you need a non-zero min, switch to `BucketSizing.CONSTANT`.
3. Pre-process values by subtracting the desired min and use CONSTANT binning instead.

Example fix

// before
new Percentiles(4096, 10.0, 1000.0, BucketSizing.LINEAR, p50, p99);

// after (option A: keep LINEAR, min=0)
new Percentiles(4096, 0.0, 1000.0, BucketSizing.LINEAR, p50, p99);
// after (option B: keep min=10, switch to CONSTANT)
new Percentiles(4096, 10.0, 1000.0, BucketSizing.CONSTANT, p50, p99);

if (bucketing == Percentiles.BucketSizing.LINEAR && Double.compare(min, 0.0d) != 0) {
    throw new IllegalArgumentException(
        "Percentiles LINEAR bucketing requires min == 0.0, got " + min);
}
new Percentiles(sizeInBytes, min, max, bucketing, percentiles);

try {
    new Percentiles(sizeInBytes, min, max, bucketing, percentiles);
} catch (IllegalArgumentException e) {
    // "Linear bucket sizing requires min to be 0.0."
    if (bucketing == Percentiles.BucketSizing.LINEAR) {
        new Percentiles(sizeInBytes, 0.0, max, bucketing, percentiles);
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling `new Percentiles(sizeInBytes, min, max, BucketSizing.LINEAR, percentiles...)` with `min != 0.0`. The convenience constructor `Percentiles(sizeInBytes, max, bucketing, percentiles...)` defaults min to 0.0 and is safe.

Common situations: A developer wants percentile latency between, say, 10ms and 1000ms and tries to set min=10 with LINEAR bucketing. Mixing up the 4-arg and 5-arg Percentiles constructors. Copying a CONSTANT-bucketing config (which allows arbitrary min) and flipping the enum to LINEAR without zeroing min.

Related errors

• Must have at least 2 bins.
• Values less than 0.0 not accepted.
• 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/4e207bce01101240.json. Report an issue: GitHub.