{"record":{"id":"b9082e60ab9aa1d7","repo":"apache/pulsar","slug":"extension-for-extensionname-attempts-to-use","errorCode":null,"errorMessage":"extension for `${extensionName}` attempts to use ${address} for its listening port. But it is already occupied by other messaging extensions","messagePattern":"extension for `(.+?)` attempts to use (.+?) for its listening port\\. But it is already occupied by other messaging extensions","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"pulsar-proxy/src/main/java/org/apache/pulsar/proxy/extensions/ProxyExtensions.java","lineNumber":133,"sourceCode":"    public void initialize(ProxyConfiguration conf) throws Exception {\n        for (ProxyExtension extension : extensions.values()) {\n            extension.initialize(conf);\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, ProxyExtensionWithClassLoader> extension : extensions.entrySet()) {\n            Map<InetSocketAddress, ChannelInitializer<SocketChannel>> initializers =\n                extension.getValue().newChannelInitializers();\n            initializers.forEach((address, initializer) -> {\n                if (!addresses.add(address)) {\n                    log.error().attr(\"extension\", extension.getKey())\n                        .attr(\"address\", address)\n                        .log(\"Extension attempts to use address already occupied\");\n                    throw new RuntimeException(\"extension for `\" + extension.getKey()\n                        + \"` attempts to use \" + address + \" for its listening port. But it is\"\n                        + \" already occupied by other messaging extensions\");\n                }\n                endpoints.put(address, extension.getKey());\n                channelInitializers.put(extension.getKey(), initializers);\n            });\n        }\n\n        return channelInitializers;\n    }\n\n    public void start(ProxyService service) {\n        extensions.values().forEach(extension -> extension.start(service));\n    }\n\n    @Override\n    public void close() {\n        extensions.values().forEach(ProxyExtension::close);","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/extensions/ProxyExtensions.java#L115-L151","documentation":"Thrown when initializing proxy extensions if two extensions declare a channel initializer for the same listen address (host:port). The proxy maintains one listener per address; a duplicate would silently hijack traffic, so load fails fast. The conflicting extension is identified in the error message.","triggerScenarios":"ProxyExtensions.newChannelInitializers() during proxy startup when two configured extensions (e.g. two protocol handlers) bind the same address, or the same address is declared both by an extension and another messaging extension.","commonSituations":"Misconfigured extension service ports that collide (e.g. both set to 6650 or 8080); two extension NARs with default configs shipped from the same template; copying an extension config block without changing its port.","solutions":["Find the duplicate address in the error message and change one extension's listen address/port to a free unique value","Audit each extension's configuration file for overlapping servicePort / webSocketPort style settings","Remove any extension listed twice or intentionally duplicated in proxyExtensionNames","Restart the proxy and verify it lists each extension's distinct endpoints at startup"],"exampleFix":"// before (extension config)\nhttpServicePort=8080\n// other extension also 8080 -> after\nhttpServicePort=8081","handlingStrategy":"validation","validationCode":"// Before deploy: assert each extension's configured listen address is unique\nMap<String, Long> dup = allExtensionAddresses.stream()\n    .collect(groupingBy(identity(), counting()));\ndup.entrySet().stream().filter(e -> e.getValue() > 1)\n   .forEach(e -> { throw new IllegalStateException(\"Duplicate address: \" + e.getKey()); });","typeGuard":null,"tryCatchPattern":"try { proxyExtensions.initialize(conf); } catch (RuntimeException e) { if (e.getMessage().contains(\"already occupied\")) log.error(\"Port conflict between extensions: {}\", e.getMessage()); throw e; }","preventionTips":["Maintain a central port allocation table for all proxy extensions","Never copy an extension config block without changing its port"],"tags":["pulsar-proxy","extensions","port-conflict"],"backgroundTag":"address-already-in-use","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}