{"id":"1713b0da3584c491","repo":"apache/kafka","slug":"must-be-at-least-1-bucket","errorCode":null,"errorMessage":"Must be at least 1 bucket","messagePattern":"Must be at least 1 bucket","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/metrics/stats/Frequencies.java","lineNumber":94,"sourceCode":"     * where the buckets are centered around the minimum, maximum, and intermediate values.\n     *\n     * @param buckets     the number of buckets; must be at least 1\n     * @param min         the minimum value to be captured\n     * @param max         the maximum value to be captured\n     * @param frequencies the list of {@link Frequency} metrics, which at most should be one per bucket centered\n     *                    on the bucket's value, though not every bucket need to correspond to a metric if the\n     *                    value is not needed\n     * @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);","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/metrics/stats/Frequencies.java#L76-L112","documentation":"Thrown by the Frequencies constructor when the buckets argument is less than 1. Frequencies needs at least one bin in its ConstantBinScheme to record any values; zero or negative buckets would produce a degenerate histogram that cannot classify samples. Note also that with buckets == 1 the bucket-width math at line 106 divides by (buckets-1) == 0 — callers should generally use at least 2 buckets.","triggerScenarios":"Calling new Frequencies(buckets, ...) with buckets <= 0, typically because the value was read from a config that defaulted to 0 or was computed from a count that turned out to be zero.","commonSituations":"Config-driven bucket counts where the property was unset or mistyped; computing buckets from a dynamic size (e.g. distinct value count) that returned 0; passing a negative constant by mistake.","solutions":["Pass buckets >= 1 (preferably >= 2 so the ConstantBinScheme width math does not divide by zero).","Default and validate any config-driven bucket count: clamp to a minimum of 2 and reject non-positive values upstream with a clearer error.","For boolean distributions use Frequencies.forBooleanValues(...) which fixes buckets=2."],"exampleFix":"// before\nnew Frequencies(0, 0.0, 1.0, freqs); // throws\n// after\nnew Frequencies(2, 0.0, 1.0, freqs);","handlingStrategy":"validation","validationCode":"// Pre-validate bucket count:\nif (buckets < 1) {\n    throw new IllegalArgumentException(\"buckets must be >= 1, got \" + buckets);\n}\nreturn new Frequencies(buckets, min, max, frequencies);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass buckets >= 1; a single bucket is the minimum useful configuration.","Validate buckets against your frequencies array length too: buckets must be >= frequencies.length.","Surface this as a configuration error to operators rather than letting it surface as a runtime exception during metric registration."],"tags":["metrics","validation","configuration"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}