apache/kafka · error · IllegalArgumentException

mBean '{mBeanName}' attribute '{templateName}' is defined tw

Error message

mBean '{mBeanName}' attribute '{templateName}' is defined twice.

What it means

Thrown by Metrics.toHtmlTable while generating the public metrics documentation table. For each MetricNameTemplate it builds a stable mBean name from (domain, group, name, tags); if two distinct templates resolve to the same mBean name AND the same attribute (template.name), the second one is rejected, because the generated HTML table and the documented MBean attribute set would otherwise be ambiguous.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/metrics/Metrics.java:285

        Map<String, Map<String, String>> beansAndAttributes = new TreeMap<>();
    
        try (Metrics metrics = new Metrics()) {
            for (MetricNameTemplate template : allMetrics) {
                Map<String, String> tags = new LinkedHashMap<>();
                for (String s : template.tags()) {
                    tags.put(s, "{" + s + "}");
                }
    
                MetricName metricName = metrics.metricName(template.name(), template.group(), template.description(), tags);
                String mBeanName = JmxReporter.getMBeanName(domain, metricName);
                if (!beansAndAttributes.containsKey(mBeanName)) {
                    beansAndAttributes.put(mBeanName, new TreeMap<>());
                }
                Map<String, String> attrAndDesc = beansAndAttributes.get(mBeanName);
                if (!attrAndDesc.containsKey(template.name())) {
                    attrAndDesc.put(template.name(), template.description());
                } else {
                    throw new IllegalArgumentException("mBean '" + mBeanName + "' attribute '" + template.name() + "' is defined twice.");
                }
            }
        }
        StringBuilder b = new StringBuilder();
        b.append("<table class=\"data-table\">\n<tbody>\n");
        b.append("<tr>\n");
        b.append("<th>Metric/Attribute name</th>\n");
        b.append("<th>Description</th>\n");
        b.append("<th>Mbean name</th>\n");
        b.append("</tr>\n");
        for (Entry<String, Map<String, String>> e : beansAndAttributes.entrySet()) {
            for (Entry<String, String> e2 : e.getValue().entrySet()) {
                b.append("<tr>\n");
                b.append("<td>");
                b.append(e2.getKey());
                b.append("</td>\n");
                b.append("<td>");
                b.append(e2.getValue());

View on GitHub (pinned to c31c9215e1)

Solutions

Inspect the templates passed to toHtmlTable and remove the duplicate MetricNameTemplate (same name + tags).
If both metrics are legitimate, differentiate them by group, name, or tags so they map to distinct mBean names.
Build the template list from a single canonical source (e.g. one constants class per module) to prevent cross-module duplicates.
Re-run the docs/table generation; the error message names the colliding mBean and attribute.

Example fix

// before: List.of(recordSendRateTemplate, recordSendRateTemplate /* duplicate */)
// after:  List.of(recordSendRateTemplate, recordRetryRateTemplate)

Defensive patterns

Strategy: validation

Validate before calling

// Before adding a metric/template, ensure (group, name) is unique within the same mBean.
Set<String> seen = new HashSet<>();
for (MetricNameTemplate t : templates) {
    String key = t.group() + ":" + t.name();
    if (!seen.add(key)) {
        throw new IllegalStateException("Duplicate metric name in group: " + key);
    }
}

Type guard

// Ensure template name uniqueness per group to avoid mBean attribute collisions.
boolean isUniqueTemplate(List<MetricNameTemplate> templates) {
    Set<String> keys = new HashSet<>();
    for (MetricNameTemplate t : templates) if (!keys.add(t.group() + ":" + t.name())) return false;
    return true;
}

Try / catch

try {
    metrics.addMetric(name, provider);
} catch (IllegalArgumentException e) {
    // duplicate mBean attribute; rename or skip registration.
}

Prevention

Metric attribute names must be unique within the same mBean (group+tags); reuse names only across disjoint groups.
When templating metrics, audit the (name, group, tags) tuple for collisions at build time.
Avoid giving two sensors metrics with identical names in the same group.
Run a preflight that builds all MetricNames and checks for duplicates.

When it happens

Trigger: Calling Metrics.toHtmlTable(domain, templates) where the iterable contains two MetricNameTemplate objects with identical name and group/tags that produce the same mBean string. Typically hit by code that aggregates templates from multiple modules and accidentally includes a duplicate, or by a template whose tags were changed such that two templates now collapse onto the same MBean.

Common situations: Maintainers regenerating the metrics documentation table after adding a new metric that reuses an existing name. Merging metric templates from two modules without deduplication. Editing a MetricNameTemplate's tags so its mBean collides with a sibling template. Running the docs generation across a broader classpath than intended.

Related errors

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