apache/kafka · error · IllegalArgumentException

The frequency centered at '{centerValue}' is not within the

Error message

The frequency centered at '{centerValue}' is not within the range [{min},{max}]

What it means

Thrown by the Frequencies constructor while validating each Frequency metric's centerValue against the configured [min, max] window. Kafka's metrics library uses Frequencies as a CompoundStat to report bucketed relative frequencies, and every Frequency must be centered inside the value range so that the underlying ConstantBinScheme can map it to a bin. The guard fails fast at construction rather than silently recording into the wrong bucket or returning NaN.

Source

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

     * @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)));
        }
        return ms;
    }

    /**

View on GitHub (pinned to c31c9215e1)

Solutions

1. Adjust the offending Frequency's centerValue so it lies within [min, max].
2. If the center value is intentional, widen `min`/`max` to include it.
3. Use `Frequencies.forBooleanValues(falseMetric, trueMetric)` for 0/1 boolean sensors so centers (0.0, 1.0) and the 0..1 range are set consistently.
4. Add a unit test asserting every Frequency center is inside the configured range.

Example fix

// before
new Frequencies(3, 0.0, 0.5,
    new Frequency(failed, 0.0),
    new Frequency(succeeded, 1.0)); // 1.0 > 0.5

// after
new Frequencies(3, 0.0, 1.0,
    new Frequency(failed, 0.0),
    new Frequency(succeeded, 1.0));

double min = ..., max = ...;
Frequency[] freqs = ...;
for (Frequency f : freqs) {
    double c = f.centerValue();
    if (Double.compare(c, min) < 0 || Double.compare(c, max) > 0) {
        throw new IllegalArgumentException(
            "Frequency centerValue " + c + " outside [" + min + "," + max + "]");
    }
}
new Frequencies(buckets, min, max, freqs);

try {
    new Frequencies(buckets, min, max, freqs);
} catch (IllegalArgumentException e) {
    // message starts with "The frequency centered at"
    log.warn("Skipping Frequencies construction: {}", e.getMessage());
}

When it happens

Trigger: Constructing `new Frequencies(buckets, min, max, frequencies...)` where any `Frequency.centerValue()` is less than `min` or greater than `max`. Also reached indirectly via `Frequencies.forBooleanValues(...)` only if a caller hand-builds Frequency objects with a center outside the supplied range.

Common situations: A developer tunes `min`/`max` to narrow the observed range but forgets to update one or more `Frequency` center values (e.g. adding a Frequency centered on 1.0 to a 0.0–0.5 range). Copy-pasting a Frequencies setup from another sensor with a different value domain. Booleans mis-modeled with non-0/1 sentinel values like -1 or 2.

Related errors

• Must have at least 2 bins.
• Linear bucket sizing requires min to be 0.0.
• The maximum value {max} must be greater than the minimum val
• Must be at least 1 bucket
• Values less than 0.0 not accepted.

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