{"id":"53dd1a7163b0d68e","repo":"apache/kafka","slug":"error-registering-mbean-mbeanname","errorCode":null,"errorMessage":"Error registering mbean {mbeanName}","messagePattern":"Error registering mbean (.+?)","errorType":"exception","errorClass":"KafkaException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/metrics/JmxReporter.java","lineNumber":216,"sourceCode":"        }\n    }\n\n    private void unregister(KafkaMbean mbean) {\n        MBeanServer server = ManagementFactory.getPlatformMBeanServer();\n        try {\n            if (server.isRegistered(mbean.name()))\n                server.unregisterMBean(mbean.name());\n        } catch (JMException e) {\n            throw new KafkaException(\"Error unregistering mbean\", e);\n        }\n    }\n\n    private void reregister(KafkaMbean mbean) {\n        unregister(mbean);\n        try {\n            ManagementFactory.getPlatformMBeanServer().registerMBean(mbean, mbean.name());\n        } catch (JMException e) {\n            throw new KafkaException(\"Error registering mbean \" + mbean.name(), e);\n        }\n    }\n\n    private static class KafkaMbean implements DynamicMBean {\n        private final ObjectName objectName;\n        private final Map<String, KafkaMetric> metrics;\n\n        KafkaMbean(String mbeanName) throws MalformedObjectNameException {\n            this.metrics = new HashMap<>();\n            this.objectName = new ObjectName(mbeanName);\n        }\n\n        public ObjectName name() {\n            return objectName;\n        }\n\n        void setAttribute(String name, KafkaMetric metric) {\n            this.metrics.put(name, metric);","sourceCodeStart":198,"sourceCodeEnd":234,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/metrics/JmxReporter.java#L198-L234","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the attached JMException cause — InstanceAlreadyExistsException points at a name collision in the same JVM.","Give each Kafka client instance a unique JMX domain prefix (configure the Metrics/JmxReporter prefix per client) so mbean ObjectNames never collide.","Ensure prior client instances are fully closed before creating new ones in long-running JVMs (tests, app servers) so their mbeans are unregistered first.","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).","Upgrade Kafka — several InstanceAlreadyExistsException races during repeated client create/close have been hardened in recent versions."],"exampleFix":"// before — two clients share the default JMX domain -> collision\nMetrics m1 = new Metrics(); new JmxReporter(m1);            // default prefix\nMetrics m2 = new Metrics(); new JmxReporter(m2);            // same default prefix -> reregister throws\n\n// after — distinct JMX domains per client\nMetrics m1 = new Metrics(); JmxReporter r1 = new JmxReporter(m1); r1.setPrefix(\"kafka.producer.a\");\nMetrics m2 = new Metrics(); JmxReporter r2 = new JmxReporter(m2); r2.setPrefix(\"kafka.producer.b\");","handlingStrategy":"try-catch","validationCode":"// Pre-check uniqueness against the platform MBeanServer before allowing registration.\nMBeanServer server = ManagementFactory.getPlatformMBeanServer();\nString mbeanName = ...; // would-be ObjectName string\ntry {\n    ObjectName on = new ObjectName(mbeanName);\n    if (server.isRegistered(on)) {\n        log.warn(\"mbean {} already registered; JmxReporter will fail to (re)register\", mbeanName);\n    }\n} catch (MalformedObjectNameException ignored) { }","typeGuard":"// Detect a malformed would-be ObjectName before it reaches JmxReporter.\nstatic boolean isValidObjectName(String name) {\n    try { new ObjectName(name); return true; }\n    catch (MalformedObjectNameException e) { return false; }\n}","tryCatchPattern":"try {\n    metrics = new Metrics(config); // triggers JmxReporter.init -> reregister\n} catch (KafkaException e) {\n    if (e.getCause() instanceof javax.management.InstanceAlreadyExistsException\n            || e.getCause() instanceof JMException) {\n        log.error(\"JMX mbean registration failed; falling back to no JMX reporter\", e.getCause());\n        rebuildMetricsWithoutJmx();\n    } else {\n        throw e;\n    }\n}","preventionTips":["Give each Metrics instance a distinct namespace/prefix (via MetricsContext) so two instances never collide on the same ObjectName.","Avoid constructing multiple Kafka clients with identical client.id in the same JVM — identical tags produce identical mbean names.","If JMX is optional, instantiate Metrics with an empty reporter list when registration keeps failing.","Check the chained cause: InstanceAlreadyExistsException, NotCompliantMBeanException, and MalformedObjectNameException each point to a different root cause."],"tags":["kafka-clients","jmx","metrics","jmx-reporter","mbean-collision"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}