alibaba/Sentinel · error · IllegalArgumentException

Incorrect number of labels.

Error message

Incorrect number of labels.

What it means

GaugeMetricFamily (Sentinel's Prometheus exporter model, mirroring prometheus client_simpleclient's GaugeMetricFamily) requires that every sample's label values match the label names declared when the family was constructed. addMetric throws IllegalArgumentException("Incorrect number of labels.") when labelValues.size() != labelNames.size(), because a Prometheus exposition-format sample must have exactly one value per declared label.

Source

Thrown at sentinel-extension/sentinel-prometheus-metric-exporter/src/main/java/com/alibaba/csp/sentinel/metric/prom/types/GaugeMetricFamily.java:53

    public GaugeMetricFamily addMetric(List<String> labelValues, double value, long timestampMs) {
        if (labelValues.size() != labelNames.size()) {
            throw new IllegalArgumentException("Incorrect number of labels.");
        }
        samples.add(new Sample(name, labelNames, labelValues, value, timestampMs));
        return this;
    }

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Compare sizes before adding: ensure labelValues.size() == the labelNames list passed to the constructor
2. Centralize the label name list in a constant and derive label value lists at the same place so they cannot drift
3. If a label is not applicable, pass an empty string (""), not a missing value — Prometheus allows empty label values

Example fix

// before
GaugeMetricFamily f = new GaugeMetricFamily("sentinel_flow", "help", List.of("resource"));
f.addMetric(List.of("foo", "bar"), 1.0, ts); // 2 values, 1 name -> throws

// after
GaugeMetricFamily f = new GaugeMetricFamily("sentinel_flow", "help", List.of("resource"));
f.addMetric(List.of("foo"), 1.0, ts);

if (labelValues.size() != LABEL_NAMES.size()) {
    throw new IllegalStateException("expected " + LABEL_NAMES.size() + " labels, got " + labelValues.size());
}
family.addMetric(labelValues, value, timestampMs);

When it happens

Trigger: Calling new GaugeMetricFamily(name, help, Arrays.asList("resource","passQps")) and then addMetric(Collections.singletonList("myResource"), 1.0, ts) — one label value for two label names throws.

Common situations: Writing a custom Collector for the sentinel-prometheus-metric-exporter module; refactoring label sets (adding a label name without updating every addMetric call site); conditional label lists where a branch supplies fewer values.

Related errors

• keys empty or null: ${keys}
• keys empty or null
• Max entry count should be at least 1:
• Invalid second interval (cannot divide by 60):
• Interval should be less than 5 min:

AI-assisted analysis of alibaba/Sentinel@a3f40ba8e9 (2026-08-14). Data as JSON: /api/errors/4ef32c6458004dc6. Report an issue: GitHub.