apache/pulsar · critical · RuntimeException

extension for `${extensionName}` attempts to use ${address}

Error message

extension for `${extensionName}` attempts to use ${address} for its listening port. But it is already occupied by other messaging extensions

What it means

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.

Source

Thrown at pulsar-proxy/src/main/java/org/apache/pulsar/proxy/extensions/ProxyExtensions.java:133

    public void initialize(ProxyConfiguration conf) throws Exception {
        for (ProxyExtension extension : extensions.values()) {
            extension.initialize(conf);
        }
    }

    public Map<String, Map<InetSocketAddress, ChannelInitializer<SocketChannel>>> newChannelInitializers() {
        Map<String, Map<InetSocketAddress, ChannelInitializer<SocketChannel>>> channelInitializers = new HashMap<>();
        Set<InetSocketAddress> addresses = new HashSet<>();

        for (Map.Entry<String, ProxyExtensionWithClassLoader> extension : extensions.entrySet()) {
            Map<InetSocketAddress, ChannelInitializer<SocketChannel>> initializers =
                extension.getValue().newChannelInitializers();
            initializers.forEach((address, initializer) -> {
                if (!addresses.add(address)) {
                    log.error().attr("extension", extension.getKey())
                        .attr("address", address)
                        .log("Extension attempts to use address already occupied");
                    throw new RuntimeException("extension for `" + extension.getKey()
                        + "` attempts to use " + address + " for its listening port. But it is"
                        + " already occupied by other messaging extensions");
                }
                endpoints.put(address, extension.getKey());
                channelInitializers.put(extension.getKey(), initializers);
            });
        }

        return channelInitializers;
    }

    public void start(ProxyService service) {
        extensions.values().forEach(extension -> extension.start(service));
    }

    @Override
    public void close() {
        extensions.values().forEach(ProxyExtension::close);

View on GitHub (pinned to 820761864e)

Solutions

1. Find the duplicate address in the error message and change one extension's listen address/port to a free unique value
2. Audit each extension's configuration file for overlapping servicePort / webSocketPort style settings
3. Remove any extension listed twice or intentionally duplicated in proxyExtensionNames
4. Restart the proxy and verify it lists each extension's distinct endpoints at startup

Example fix

// before (extension config)
httpServicePort=8080
// other extension also 8080 -> after
httpServicePort=8081

// Before deploy: assert each extension's configured listen address is unique
Map<String, Long> dup = allExtensionAddresses.stream()
    .collect(groupingBy(identity(), counting()));
dup.entrySet().stream().filter(e -> e.getValue() > 1)
   .forEach(e -> { throw new IllegalStateException("Duplicate address: " + e.getKey()); });

try { proxyExtensions.initialize(conf); } catch (RuntimeException e) { if (e.getMessage().contains("already occupied")) log.error("Port conflict between extensions: {}", e.getMessage()); throw e; }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to load the extension for extension name `${extension
• Malformed extension found for extension name `${extensionNam
• extension `${name}` does NOT provide a protocol handler impl
• Class ${extensionClass} does not implement extension interfa
• Failed to bind extension `${extensionName}` on ${address}

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/b9082e60ab9aa1d7. Report an issue: GitHub.