What causes "The number of samples must be at least 1." in apache/kafka?

Pass a value >= 1 to MetricConfig.samples(int).

apache/kafka · error · IllegalArgumentException

The number of samples must be at least 1.

Error message

The number of samples must be at least 1.

What it means

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.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/metrics/MetricConfig.java:92

        return this;
    }

    public Map<String, String> tags() {
        return this.tags;
    }

    public MetricConfig tags(Map<String, String> tags) {
        this.tags = tags;
        return this;
    }

    public int samples() {
        return this.samples;
    }

    public MetricConfig samples(int samples) {
        if (samples < 1)
            throw new IllegalArgumentException("The number of samples must be at least 1.");
        this.samples = samples;
        return this;
    }

    public Sensor.RecordingLevel recordLevel() {
        return this.recordingLevel;
    }

    public MetricConfig recordLevel(Sensor.RecordingLevel recordingLevel) {
        this.recordingLevel = recordingLevel;
        return this;
    }


}

View on GitHub (pinned to c31c9215e1)

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.

Example fix

// before: MetricConfig cfg = new MetricConfig().samples(0);
// after:  MetricConfig cfg = new MetricConfig().samples(Math.max(1, configuredSamples));

Defensive patterns

Strategy: validation

Validate before calling

// Validate sample count before constructing MetricConfig.
int requestedSamples = ...;
if (requestedSamples < 1) {
    throw new IllegalArgumentException("samples must be >= 1; got " + requestedSamples);
}
MetricConfig config = new MetricConfig().samples(Math.max(1, requestedSamples));

Type guard

// Bound samples to the valid domain [1, Integer.MAX_VALUE] before calling samples(int).
int safeSamples(int n) { return (n < 1) ? 1 : n; }

Prevention

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.

When it happens

Trigger: 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().

Common situations: 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.

Related errors

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