apache/kafka · error · IllegalArgumentException

Meter is supported only for WindowedCount or WindowedSum.

Error message

Meter is supported only for WindowedCount or WindowedSum.

What it means

Thrown by the Meter constructor when the supplied `rateStat` is not a `WindowedSum` (which includes its subclass `WindowedCount`). Meter pairs a windowed rate with a `CumulativeSum` total, and its `record()` method branches on `rate.stat instanceof WindowedCount` to decide whether to record the event count (1.0) or the recorded value. Any other SampledStat (Avg, Max, Percentiles, etc.) would break that contract, so it is rejected.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/metrics/stats/Meter.java:65

     * Construct a Meter with provided time unit
     */
    public Meter(TimeUnit unit, MetricName rateMetricName, MetricName totalMetricName) {
        this(unit, new WindowedSum(), rateMetricName, totalMetricName);
    }

    /**
     * Construct a Meter with seconds as time unit
     */
    public Meter(SampledStat rateStat, MetricName rateMetricName, MetricName totalMetricName) {
        this(TimeUnit.SECONDS, rateStat, rateMetricName, totalMetricName);
    }

    /**
     * Construct a Meter with provided time unit
     */
    public Meter(TimeUnit unit, SampledStat rateStat, MetricName rateMetricName, MetricName totalMetricName) {
        if (!(rateStat instanceof WindowedSum)) {
            throw new IllegalArgumentException("Meter is supported only for WindowedCount or WindowedSum.");
        }
        this.total = new CumulativeSum();
        this.rate = new Rate(unit, rateStat);
        this.rateMetricName = rateMetricName;
        this.totalMetricName = totalMetricName;
    }

    @Override
    public List<NamedMeasurable> stats() {
        return Arrays.asList(
            new NamedMeasurable(totalMetricName, total),
            new NamedMeasurable(rateMetricName, rate));
    }

    @Override
    public void record(MetricConfig config, double value, long timeMs) {
        rate.record(config, value, timeMs);
        // Total metrics with Count stat should record 1.0 (as recorded in the count)

View on GitHub (pinned to c31c9215e1)

Solutions

1. Pass `new WindowedSum()` (default; used by the convenience constructors `new Meter(rateName, totalName)`).
2. Pass `new WindowedCount()` if you want event-count rate rather than sum-of-values rate.
3. If you actually need a rate of Avg/Max/Percentile, register those as separate Sensor stats and compute rate manually — do not wrap them in a Meter.

Example fix

// before
new Meter(new Avg(), rateName, totalName);

// after
new Meter(new WindowedSum(), rateName, totalName);
// or for event-count rate:
new Meter(new WindowedCount(), rateName, totalName);

if (!(rateStat instanceof WindowedSum)) {
    throw new IllegalArgumentException(
        "Meter rateStat must be WindowedSum or WindowedCount, got " + rateStat.getClass());
}
new Meter(unit, rateStat, rateMetricName, totalMetricName);

static SampledStat asMeterable(SampledStat s) {
    if (s instanceof WindowedSum) return s;
    throw new IllegalArgumentException(
        "Meter requires WindowedSum/WindowedCount, got " + s.getClass());
}

try {
    new Meter(unit, rateStat, rateMetricName, totalMetricName);
} catch (IllegalArgumentException e) {
    // "Meter is supported only for WindowedCount or WindowedSum."
    new Meter(unit, new WindowedSum(), rateMetricName, totalMetricName);
}

When it happens

Trigger: Calling `new Meter(unit, rateStat, rateMetricName, totalMetricName)` or `new Meter(rateStat, rateMetricName, totalMetricName)` with `rateStat` that is not a WindowedSum/WindowedCount (e.g. `new Avg()`, `new Max()`, a `Percentiles` instance).

Common situations: A developer tries to build a 'rate of average latency' or 'rate of max' meter by passing a different SampledStat. Copy-pasting Meter construction from sample code that used WindowedSum and substituting another stat. Misreading the message — it says 'WindowedCount or WindowedSum' because WindowedCount extends WindowedSum, so the instanceof check covers both.

Related errors

• The frequency centered at '{centerValue}' is not within the
• Must have at least 2 bins.
• Values less than 0.0 not accepted.
• Linear bucket sizing requires min to be 0.0.
• Expected 0 <= minVersion <= maxVersion but received minVersi

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