{"id":"75079791e33ecd01","repo":"apache/kafka","slug":"the-number-of-samples-must-be-at-least-1","errorCode":null,"errorMessage":"The number of samples must be at least 1.","messagePattern":"The number of samples must be at least 1\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/metrics/MetricConfig.java","lineNumber":92,"sourceCode":"        return this;\n    }\n\n    public Map<String, String> tags() {\n        return this.tags;\n    }\n\n    public MetricConfig tags(Map<String, String> tags) {\n        this.tags = tags;\n        return this;\n    }\n\n    public int samples() {\n        return this.samples;\n    }\n\n    public MetricConfig samples(int samples) {\n        if (samples < 1)\n            throw new IllegalArgumentException(\"The number of samples must be at least 1.\");\n        this.samples = samples;\n        return this;\n    }\n\n    public Sensor.RecordingLevel recordLevel() {\n        return this.recordingLevel;\n    }\n\n    public MetricConfig recordLevel(Sensor.RecordingLevel recordingLevel) {\n        this.recordingLevel = recordingLevel;\n        return this;\n    }\n\n\n}\n","sourceCodeStart":74,"sourceCodeEnd":108,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/metrics/MetricConfig.java#L74-L108","documentation":"Thrown by MetricConfig.samples(int) when the caller tries to set the sample count below 1. Kafka Sensors keep a rolling window of sample buffers to compute windowed statistics; zero samples would mean no statistics can ever be collected, so the builder rejects it at construction time with IllegalArgumentException.","triggerScenarios":"Application code calls new MetricConfig().samples(0) or .samples(negative). It can also surface when a config-driven path (e.g. metrics.sample.window.ms plus a samples value parsed from properties) maps an empty/invalid property to 0 and forwards it to MetricConfig.samples().","commonSituations":"Setting metrics.num.samples=0 in client/broker properties. Off-by-one bugs computing sample count from a divisor. Disabling metrics collection by zeroing the sample count instead of using a higher RecordingLevel or removing the reporter. Defaulting an int field to 0 and passing it through without validation.","solutions":["Pass a value >= 1 to MetricConfig.samples(int).","If the value comes from configuration, validate/parse it to at least 1 before calling samples() (e.g. Math.max(1, configured)).","To disable metrics, drop the JmxReporter / use Sensor.RecordingLevel.INFO or remove the sensor instead of zeroing samples."],"exampleFix":"// before: MetricConfig cfg = new MetricConfig().samples(0);\n// after:  MetricConfig cfg = new MetricConfig().samples(Math.max(1, configuredSamples));","handlingStrategy":"validation","validationCode":"// Validate sample count before constructing MetricConfig.\nint requestedSamples = ...;\nif (requestedSamples < 1) {\n    throw new IllegalArgumentException(\"samples must be >= 1; got \" + requestedSamples);\n}\nMetricConfig config = new MetricConfig().samples(Math.max(1, requestedSamples));","typeGuard":"// Bound samples to the valid domain [1, Integer.MAX_VALUE] before calling samples(int).\nint safeSamples(int n) { return (n < 1) ? 1 : n; }","tryCatchPattern":null,"preventionTips":["Clamp user-provided sample counts to >= 1 at the config boundary.","Default MetricConfig.samples is 2; only override with a positive int.","Avoid exposing raw samples config to end users without validation.","Document that samples controls memory (windowed stat buffers) so over-large values are also suspect."],"tags":["config","metrics","validation","samples"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}