apache/kafka · error · IllegalArgumentException

Must specify at least one metric name

Error message

Must specify at least one metric name

What it means

Thrown by Frequencies.forBooleanValues when both the falseMetricName and trueMetricName arguments are null — the resulting Frequencies object would have zero Frequency metrics and therefore report nothing. forBooleanValues exists specifically to build a two-bucket boolean distribution; passing null for both is a misuse because the helper cannot construct a meaningful metric set.

Source

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

    /**
     * Create a Frequencies instance with metrics for the frequency of a boolean sensor that records 0.0 for
     * false and 1.0 for true.
     *
     * @param falseMetricName the name of the metric capturing the frequency of failures; may be null if not needed
     * @param trueMetricName  the name of the metric capturing the frequency of successes; may be null if not needed
     * @return the Frequencies instance; never null
     * @throws IllegalArgumentException if both {@code falseMetricName} and {@code trueMetricName} are null
     */
    public static Frequencies forBooleanValues(MetricName falseMetricName, MetricName trueMetricName) {
        List<Frequency> frequencies = new ArrayList<>();
        if (falseMetricName != null) {
            frequencies.add(new Frequency(falseMetricName, 0.0));
        }
        if (trueMetricName != null) {
            frequencies.add(new Frequency(trueMetricName, 1.0));
        }
        if (frequencies.isEmpty()) {
            throw new IllegalArgumentException("Must specify at least one metric name");
        }
        Frequency[] frequencyArray = frequencies.toArray(new Frequency[0]);
        return new Frequencies(2, 0.0, 1.0, frequencyArray);
    }

    private final Frequency[] frequencies;
    private final BinScheme binScheme;

    /**
     * Create a Frequencies that captures the values in the specified range into the given number of buckets,
     * where the buckets are centered around the minimum, maximum, and intermediate values.
     *
     * @param buckets     the number of buckets; must be at least 1
     * @param min         the minimum value to be captured
     * @param max         the maximum value to be captured
     * @param frequencies the list of {@link Frequency} metrics, which at most should be one per bucket centered
     *                    on the bucket's value, though not every bucket need to correspond to a metric if the
     *                    value is not needed

View on GitHub (pinned to c31c9215e1)

Solutions

1. Pass at least one non-null MetricName — typically both falseMetricName and trueMetricName for a boolean sensor.
2. If only one side is of interest, pass the other as null (allowed) but never both.
3. Validate inputs upstream (config presence) before calling forBooleanValues, and fail loudly with a clearer error if config is missing.

Example fix

// before
Frequencies.forBooleanValues(null, null); // throws
// after
Frequencies.forBooleanValues(
    metrics.metricName("fail-rate", ..., ...),
    metrics.metricName("success-rate", ..., ...)
);

// Pre-validate before calling Frequencies.forBooleanValues(falseName, trueName):
if (falseMetricName == null && trueMetricName == null) {
    throw new IllegalArgumentException(
        "At least one of falseMetricName / trueMetricName must be non-null");
}
return Frequencies.forBooleanValues(falseMetricName, trueMetricName);

When it happens

Trigger: Calling Frequencies.forBooleanValues(null, null). This happens when both metric name arguments are conditionally computed and every branch evaluates to null, or when a caller passes a field that was never initialized.

Common situations: Building boolean frequencies from optional config where neither success nor failure metric was configured; refactoring that replaces a MetricName with null accidentally; defaulting method parameters to null without a fallback.

Related errors

• The target time for partition {} is {}. The target time cann
• At least one valid string must be provided when empty values
• Not a measurable: {metricValueProviderClass}
• The number of samples must be at least 1.
• For '{templateName}', runtime-defined metric tags do not mat

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