apache/kafka · error · KafkaException

Error creating mbean attribute for metricName :{metricName}

Error message

Error creating mbean attribute for metricName :{metricName}

What it means

Thrown by JmxReporter.addAttribute(KafkaMetric) when constructing or registering a JMX attribute for a metric fails with a JMException (e.g. MalformedObjectNameException, the metric name produced an invalid ObjectName, or the attribute could not be associated). Kafka wraps the cause in a KafkaException so metric-reporting failures during metric registration are not silently lost. The message includes the full metricName so the offending metric is identifiable.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/metrics/JmxReporter.java:170

    private KafkaMbean removeAttribute(KafkaMetric metric, String mBeanName) {
        MetricName metricName = metric.metricName();
        KafkaMbean mbean = this.mbeans.get(mBeanName);
        if (mbean != null)
            mbean.removeAttribute(metricName.name());
        return mbean;
    }

    private String addAttribute(KafkaMetric metric) {
        try {
            MetricName metricName = metric.metricName();
            String mBeanName = getMBeanName(prefix, metricName);
            if (!this.mbeans.containsKey(mBeanName))
                mbeans.put(mBeanName, new KafkaMbean(mBeanName));
            KafkaMbean mbean = this.mbeans.get(mBeanName);
            mbean.setAttribute(metricName.name(), metric);
            return mBeanName;
        } catch (JMException e) {
            throw new KafkaException("Error creating mbean attribute for metricName :" + metric.metricName(), e);
        }
    }

    /**
     * @param metricName
     * @return standard JMX MBean name in the following format domainName:type=metricType,key1=val1,key2=val2
     */
    static String getMBeanName(String prefix, MetricName metricName) {
        StringBuilder mBeanName = new StringBuilder();
        mBeanName.append(prefix);
        mBeanName.append(":type=");
        mBeanName.append(metricName.group());
        for (Map.Entry<String, String> entry : metricName.tags().entrySet()) {
            if (entry.getKey().isEmpty() || entry.getValue().isEmpty())
                continue;
            mBeanName.append(",");
            mBeanName.append(entry.getKey());
            mBeanName.append("=");

View on GitHub (pinned to c31c9215e1)

Solutions

1. Read the attached JMException cause — it specifies whether the failure is a malformed name, a duplicate, or an MBean-server rejection.
2. Inspect the metricName in the message: if a tag value is the culprit, sanitize or rename the tag at the point you create the Sensor/MetricName.
3. If you do not need JMX, disable the JmxReporter (don't add it to Metrics, or set auto-generated JMX domain to a non-conflicting value) so metric registration no longer touches the MBean server.
4. If JMX is required, ensure your JMX domain prefix and metric group/tag values are short, ASCII, and free of characters the Sanitizer does not escape.
5. Check the runtime env: confirm the process has permission to register mbeans (no restrictive SecurityManager / JMX auth misconfiguration) and that another process has not already registered a clashing ObjectName.

Example fix

// before — metric tag with a value that breaks JMX
MetricName name = metrics.metricName("queue-size", "app",
    Map.of("path", tenantPath));           // e.g. "orders/eu-west-1"
metrics.addMetric(name, (c, now) -> queue.size());   // JmxReporter.addAttribute throws

// after — sanitize tag values before building the metric
String safePath = tenantPath.replaceAll("[^a-zA-Z0-9._-]", "_");
MetricName name = metrics.metricName("queue-size", "app",
    Map.of("path", safePath));
metrics.addMetric(name, (c, now) -> queue.size());

// No API exists to pre-flight a single metric; instead keep metric names and tags JMX-safe.
// Ensure MetricName.group(), tags keys/values are non-null and ASCII-safe.
MetricName name = new MetricName("records", "my-group", "desc", Map.of("client-id", clientId));
assert name.group().matches("[a-zA-Z0-9._-]+") : "group must be JMX-safe";
assert !name.tags().containsValue(null) : "null tag values break JMX";

// Reject metric names whose group/tags would produce a malformed ObjectName.
static boolean isJmxSafe(MetricName n) {
    if (n.group() == null || n.group().isEmpty()) return false;
    for (var e : n.tags().entrySet()) {
        if (e.getKey() == null || e.getValue() == null) return false;
        if (e.getKey().contains(",") || e.getKey().contains(":") || e.getKey().contains("=")) return false;
    }
    return true;
}

try {
    metrics.addMetric(metricName, measurable);
} catch (KafkaException e) {
    // JmxReporter chains the JMException as cause; degrade by disabling JMX rather than crashing.
    if (e.getCause() instanceof JMException) {
        log.error("JMX registration failed for {}; disabling JMX reporter", metricName, e.getCause());
        disableJmxReporter();
    } else {
        throw e;
    }
}

When it happens

Trigger: A new KafkaMetric is added to a Metrics instance that has JmxReporter installed; addAttribute() builds the mbean name via getMBeanName() and calls KafkaMbean.setAttribute(); if KafkaMbean's ObjectName construction throws or setAttribute encounters a JMException, the exception propagates here and is rethrown. Triggered by AdminClient/KafkaProducer/KafkaConsumer/KafkaStreams construction (or first metric add) when JMX metrics are enabled (default).

Common situations: A metric group or tag value contains characters that break JMX ObjectName syntax despite the Sanitizer.jmxSanitize() pass (e.g. extremely long values, reserved domain fragments); a custom Sensor added with a name colliding with an existing mbean in a different domain; running in a container/JVM that restricts JMX (SecurityManager / limited platform MBean server); JMX port/domain misconfiguration via `com.sun.management.jmxremote.*` system properties; a plugin registering metrics with weird tags.

Related errors

• Error unregistering mbean
• Error registering mbean {mbeanName}
• Could not find attribute {name}
• JMX filter for configuration{metricsConfigPrefix}.(include/e
• JMX MetricsContext can only be updated before JMX metrics ar

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