apache/kafka · error · KafkaException

Error registering mbean {mbeanName}

Error message

Error registering mbean {mbeanName}

What it means

Thrown by JmxReporter.reregister(KafkaMbean) when ManagementFactory.getPlatformMBeanServer().registerMBean() raises a JMException (e.g. InstanceAlreadyExistsException, MBeanRegistrationException). reregister() first calls unregister() then registerMBean(); if registration still fails — typically because the mbean name is already taken by another component in the same JVM — the JMException is wrapped and rethrown with the offending mbean name in the message.

Source

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

        }
    }

    private void unregister(KafkaMbean mbean) {
        MBeanServer server = ManagementFactory.getPlatformMBeanServer();
        try {
            if (server.isRegistered(mbean.name()))
                server.unregisterMBean(mbean.name());
        } catch (JMException e) {
            throw new KafkaException("Error unregistering mbean", e);
        }
    }

    private void reregister(KafkaMbean mbean) {
        unregister(mbean);
        try {
            ManagementFactory.getPlatformMBeanServer().registerMBean(mbean, mbean.name());
        } catch (JMException e) {
            throw new KafkaException("Error registering mbean " + mbean.name(), e);
        }
    }

    private static class KafkaMbean implements DynamicMBean {
        private final ObjectName objectName;
        private final Map<String, KafkaMetric> metrics;

        KafkaMbean(String mbeanName) throws MalformedObjectNameException {
            this.metrics = new HashMap<>();
            this.objectName = new ObjectName(mbeanName);
        }

        public ObjectName name() {
            return objectName;
        }

        void setAttribute(String name, KafkaMetric metric) {
            this.metrics.put(name, metric);

View on GitHub (pinned to c31c9215e1)

Solutions

1. Read the attached JMException cause — InstanceAlreadyExistsException points at a name collision in the same JVM.
2. Give each Kafka client instance a unique JMX domain prefix (configure the Metrics/JmxReporter prefix per client) so mbean ObjectNames never collide.
3. Ensure prior client instances are fully closed before creating new ones in long-running JVMs (tests, app servers) so their mbeans are unregistered first.
4. In container/app-server deployments, disable Kafka's JmxReporter if the container already exposes metrics, or expose Kafka metrics via a different sink (Prometheus agent).
5. Upgrade Kafka — several InstanceAlreadyExistsException races during repeated client create/close have been hardened in recent versions.

Example fix

// before — two clients share the default JMX domain -> collision
Metrics m1 = new Metrics(); new JmxReporter(m1);            // default prefix
Metrics m2 = new Metrics(); new JmxReporter(m2);            // same default prefix -> reregister throws

// after — distinct JMX domains per client
Metrics m1 = new Metrics(); JmxReporter r1 = new JmxReporter(m1); r1.setPrefix("kafka.producer.a");
Metrics m2 = new Metrics(); JmxReporter r2 = new JmxReporter(m2); r2.setPrefix("kafka.producer.b");

// Pre-check uniqueness against the platform MBeanServer before allowing registration.
MBeanServer server = ManagementFactory.getPlatformMBeanServer();
String mbeanName = ...; // would-be ObjectName string
try {
    ObjectName on = new ObjectName(mbeanName);
    if (server.isRegistered(on)) {
        log.warn("mbean {} already registered; JmxReporter will fail to (re)register", mbeanName);
    }
} catch (MalformedObjectNameException ignored) { }

// Detect a malformed would-be ObjectName before it reaches JmxReporter.
static boolean isValidObjectName(String name) {
    try { new ObjectName(name); return true; }
    catch (MalformedObjectNameException e) { return false; }
}

try {
    metrics = new Metrics(config); // triggers JmxReporter.init -> reregister
} catch (KafkaException e) {
    if (e.getCause() instanceof javax.management.InstanceAlreadyExistsException
            || e.getCause() instanceof JMException) {
        log.error("JMX mbean registration failed; falling back to no JMX reporter", e.getCause());
        rebuildMetricsWithoutJmx();
    } else {
        throw e;
    }
}

When it happens

Trigger: A KafkaMetric is updated in a way that requires re-registering its mbean (e.g. tags change and the mbean name shifts), JmxReporter.reregister() runs after unregister, and the platform MBeanServer rejects the new registration. Also happens when two Kafka client instances in the same JVM use the same JMX domain and ObjectName, or an external component has already registered an mbean at that name.

Common situations: Multiple KafkaProducer/Consumer/AdminClient instances in one JVM with the default (or identical) JMX domain prefix; an application server (Tomcat, JBoss, Spring Boot) that already exposes Kafka mbeans and clashes with Kafka's own JmxReporter; running Kafka Streams with multiple threads each constructing a client that registers metrics with colliding names; redeployment of a webapp without fully cleaning prior mbeans; running tests that instantiate clients repeatedly in the same JVM.

Related errors

• Error creating mbean attribute for metricName :{metricName}
• Error unregistering mbean
• Could not find attribute {name}
• Set not allowed.
• JMX filter for configuration{metricsConfigPrefix}.(include/e

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