{"id":"5a9b5fd2139b991c","repo":"apache/kafka","slug":"the-frequency-centered-at-centervalue-is-not-w","errorCode":null,"errorMessage":"The frequency centered at '{centerValue}' is not within the range [{min},{max}]","messagePattern":"The frequency centered at '(.+?)' is not within the range \\[(.+?),(.+?)\\]","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/metrics/stats/Frequencies.java","lineNumber":102,"sourceCode":"     * @throws IllegalArgumentException if any of the {@link Frequency} objects do not have a\n     *                                  {@link Frequency#centerValue() center value} within the specified range\n     */\n    public Frequencies(int buckets, double min, double max, Frequency... frequencies) {\n        super(0.0); // initial value is unused by this implementation\n        if (max < min) {\n            throw new IllegalArgumentException(\"The maximum value \" + max\n                                                       + \" must be greater than the minimum value \" + min);\n        }\n        if (buckets < 1) {\n            throw new IllegalArgumentException(\"Must be at least 1 bucket\");\n        }\n        if (buckets < frequencies.length) {\n            throw new IllegalArgumentException(\"More frequencies than buckets\");\n        }\n        this.frequencies = frequencies;\n        for (Frequency freq : frequencies) {\n            if (min > freq.centerValue() || max < freq.centerValue()) {\n                throw new IllegalArgumentException(\"The frequency centered at '\" + freq.centerValue()\n                                                           + \"' is not within the range [\" + min + \",\" + max + \"]\");\n            }\n        }\n        double halfBucketWidth = (max - min) / (buckets - 1) / 2.0;\n        this.binScheme = new ConstantBinScheme(buckets, min - halfBucketWidth, max + halfBucketWidth);\n    }\n\n    @Override\n    public List<NamedMeasurable> stats() {\n        List<NamedMeasurable> ms = new ArrayList<>(frequencies.length);\n        for (Frequency frequency : frequencies) {\n            final double center = frequency.centerValue();\n            ms.add(new NamedMeasurable(frequency.name(), (config, now) -> frequency(config, now, center)));\n        }\n        return ms;\n    }\n\n    /**","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/metrics/stats/Frequencies.java#L84-L120","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Adjust the offending Frequency's centerValue so it lies within [min, max].","If the center value is intentional, widen `min`/`max` to include it.","Use `Frequencies.forBooleanValues(falseMetric, trueMetric)` for 0/1 boolean sensors so centers (0.0, 1.0) and the 0..1 range are set consistently.","Add a unit test asserting every Frequency center is inside the configured range."],"exampleFix":"// before\nnew Frequencies(3, 0.0, 0.5,\n    new Frequency(failed, 0.0),\n    new Frequency(succeeded, 1.0)); // 1.0 > 0.5\n\n// after\nnew Frequencies(3, 0.0, 1.0,\n    new Frequency(failed, 0.0),\n    new Frequency(succeeded, 1.0));","handlingStrategy":"validation","validationCode":"double min = ..., max = ...;\nFrequency[] freqs = ...;\nfor (Frequency f : freqs) {\n    double c = f.centerValue();\n    if (Double.compare(c, min) < 0 || Double.compare(c, max) > 0) {\n        throw new IllegalArgumentException(\n            \"Frequency centerValue \" + c + \" outside [\" + min + \",\" + max + \"]\");\n    }\n}\nnew Frequencies(buckets, min, max, freqs);","typeGuard":null,"tryCatchPattern":"try {\n    new Frequencies(buckets, min, max, freqs);\n} catch (IllegalArgumentException e) {\n    // message starts with \"The frequency centered at\"\n    log.warn(\"Skipping Frequencies construction: {}\", e.getMessage());\n}","preventionTips":["Pick min/max from the actual span of all Frequency.centerValue() values before constructing Frequencies.","When using forBooleanValues, rely on the helper which sets min=0.0/max=1.0 matching its centers.","Add a unit test that asserts every Frequency center lies in [min,max] for your metric set.","Treat Frequencies as configuration-of-record: validate the whole (min,max,centers) tuple in one place, not piecemeal."],"tags":["metrics","frequencies","configuration","validation","java"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}