{"record":{"id":"d9f23c02e8aa00e5","repo":"apache/pulsar","slug":"protocol-handler-for-handler-attempts-to-use","errorCode":null,"errorMessage":"Protocol handler for `${handler}` attempts to use ${address} for its listening port. But it is already occupied by other messaging protocols","messagePattern":"Protocol handler for `(.+?)` attempts to use (.+?) for its listening port\\. But it is already occupied by other messaging protocols","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/protocol/ProtocolHandlers.java","lineNumber":145,"sourceCode":"                e -> e.getValue().getProtocolDataToAdvertise()\n            ));\n    }\n\n    public Map<String, Map<InetSocketAddress, ChannelInitializer<SocketChannel>>> newChannelInitializers() {\n        Map<String, Map<InetSocketAddress, ChannelInitializer<SocketChannel>>> channelInitializers = new HashMap<>();\n        Set<InetSocketAddress> addresses = new HashSet<>();\n\n        for (Map.Entry<String, ProtocolHandlerWithClassLoader> handler : handlers.entrySet()) {\n            Map<InetSocketAddress, ChannelInitializer<SocketChannel>> initializers =\n                handler.getValue().newChannelInitializers();\n            initializers.forEach((address, initializer) -> {\n                if (!addresses.add(address)) {\n                    log.error()\n                            .attr(\"handler\", handler.getKey())\n                            .attr(\"address\", address)\n                            .log(\"Protocol handler attempts to use listening port already occupied by other\"\n                                    + \" messaging protocols\");\n                    throw new RuntimeException(\"Protocol handler for `\" + handler.getKey()\n                        + \"` attempts to use \" + address + \" for its listening port. But it is\"\n                        + \" already occupied by other messaging protocols\");\n                }\n                channelInitializers.put(handler.getKey(), initializers);\n                endpoints.put(address, handler.getKey());\n            });\n        }\n\n        return channelInitializers;\n    }\n\n    public void start(BrokerService service) {\n        handlers.values().forEach(handler -> handler.start(service));\n    }\n\n    @Override\n    public void close() {\n        handlers.values().forEach(ProtocolHandler::close);","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/protocol/ProtocolHandlers.java#L127-L163","documentation":"Thrown by ProtocolHandlers.newChannelInitializers when two messaging protocol handlers try to bind the same listening address. Each address may be owned by exactly one protocol; a duplicate would create ambiguous channel initialization.","triggerScenarios":"During broker service startup, multiple configured handlers return the same bind address from getProtocolDataToAdvertise/endpoint setup, so addresses.add(address) returns false.","commonSituations":"Two protocol NARs (e.g. kafka-on-pulsar with two listeners) configured with identical host:port; duplicated bindAddress entries in handler configuration; copy-pasted listener config between protocols.","solutions":["Give each protocol handler a unique listen address/port in its configuration.","If one handler should serve multiple protocol names, register it once and let it expose multiple endpoints internally instead of loading it twice.","Review the broker.conf / handler-specific conf for duplicated bindAddress values and remove the duplicate.","Restart after fixing; the log names both the conflicting handler and address."],"exampleFix":"// before\nkafkaBindAddress=0.0.0.0:6650\nkopaBindAddress=0.0.0.0:6650\n// after\nkafkaBindAddress=0.0.0.0:6650\nkopaBindAddress=0.0.0.0:6651","handlingStrategy":"validation","validationCode":"// Pre-startup check: all handler bind addresses must be unique\njava.util.Set<String> seen = new java.util.HashSet<>();\nfor (String addr : allHandlerBindAddresses) { // gathered from each handler's conf\n  if (!seen.add(addr))\n    throw new IllegalStateException(\"Duplicate bind address across protocol handlers: \" + addr);\n}","typeGuard":null,"tryCatchPattern":"try {\n  handlers = ProtocolHandlers.load(conf);\n} catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"already occupied by other messaging protocols\")) {\n    log.error(\"Two handlers claim the same listen address; assign unique ports\");\n  }\n  throw e;\n}","preventionTips":["Assign each protocol handler a unique listen port","Keep a central port allocation table for the broker host","Review handler configs after copy-pasting listener sections","Check pre-start logs listing endpoints per handler"],"tags":["broker","port-conflict","protocol-handler","configuration"],"backgroundTag":"port-already-in-use","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}