apache/pulsar · error · IllegalArgumentException

bindAddresses: conflicting listener names for ${address}: `$

Error message

bindAddresses: conflicting listener names for ${address}: `${existingListener}` and `${listener}`

What it means

IllegalArgumentException thrown by BindAddressValidator.validateBindAddresses when two bindAddresses entries resolve to the same ip:port but declare different listener names. Exact duplicates (same address and same listener name) are tolerated, but a shared socket bound under two distinct listener names is ambiguous, so validation fails. This prevents one socket from being reachable under conflicting listener identities.

Source

Thrown at pulsar-broker-common/src/main/java/org/apache/pulsar/broker/validator/BindAddressValidator.java:103

        // apply the filter
        if (schemes != null) {
            addresses.removeIf(a -> !schemes.contains(a.getAddress().getScheme()));
        }

        // Deduplicate by full URI (scheme + ip + port). Tolerate exact duplicates (same URI and
        // same listener name) so that a user's bindAddresses entry that matches a migrated binding
        // is accepted; reject same URI assigned to different listener names.
        Map<URI, BindAddress> uniqueBindAddresses = new LinkedHashMap<>();
        for (BindAddress addr : addresses) {
            BindAddress existing = uniqueBindAddresses.get(addr.getAddress());
            if (existing == null) {
                uniqueBindAddresses.put(addr.getAddress(), addr);
            } else if (Objects.equals(existing.getListenerName(), addr.getListenerName())) {
                // exact duplicate, tolerate
                continue;
            } else {
                throw new IllegalArgumentException("bindAddresses: conflicting listener names for "
                        + addr.getAddress() + ": `" + existing.getListenerName() + "` and `"
                        + addr.getListenerName() + "`");
            }
        }

        // ip:port uniqueness across protocol schemes. A TCP socket can only be bound by one
        // listener+scheme combination, so two bindings that share host:port but differ in scheme
        // (e.g. pulsar://0.0.0.0:8080 and http://0.0.0.0:8080) cannot both be active. Port 0 is
        // skipped because it means "OS-assigned ephemeral port" — the kernel will hand out a unique
        // port to each socket, so two port-0 entries with the same IP cannot actually collide.
        Map<String, BindAddress> uniqueIpPort = new LinkedHashMap<>();
        for (BindAddress addr : uniqueBindAddresses.values()) {
            if (addr.getAddress().getPort() == 0) {
                continue;
            }
            String ipPort = MultipleListenerValidator.formatHostPort(addr.getAddress());
            BindAddress prior = uniqueIpPort.putIfAbsent(ipPort, addr);
            if (prior != null) {

View on GitHub (pinned to 820761864e)

Solutions

1. Give each ip:port a single listener name — deduplicate or drop the conflicting entry
2. If two names were intended, bind them to different ports/hosts
3. Verify resolved addresses (DNS) to spot accidental same-IP collisions
4. Keep an exact duplicate only if the listener names match (that case is tolerated)

Example fix

// before
bindAddresses=a:pulsar://10.0.0.1:6650,b:pulsar://10.0.0.1:6650
// after
bindAddresses=a:pulsar://10.0.0.1:6650,b:pulsar://10.0.0.2:6650

Map<String,String> byIpPort = new HashMap<>();
for (String s : bindAddresses.split(",")) {
    URI u = URI.create(s.substring(s.indexOf(':') + 1));
    String key = u.getHost() + ":" + u.getPort();
    String name = s.substring(0, s.indexOf(':'));
    String prev = byIpPort.put(key, name);
    if (prev != null && !prev.equals(name)) {
        throw new IllegalArgumentException("Conflicting listener names for " + key + ": " + prev + " vs " + name);
    }
}

When it happens

Trigger: bindAddresses containing e.g. a:pulsar://10.0.0.1:6650 and b:pulsar://10.0.0.1:6650 — same host:port, different listener names. Wildcard/0.0.0.0 entries can also collide with specific-interface entries mapping to the same resolved address.

Common situations: Copy-pasting a listener entry to create a second listener but forgetting to change host or port; DNS names resolving to the same IP with different listener names; container/k8s configs where 0.0.0.0 and an explicit pod IP both appear.

Related errors

• bindAddresses: malformed: ${address}
• bindAddresses: ip:port `${ipPort}` is bound by two schemes:
• Protocol handler for `${handler}` attempts to use ${address}
• host must not be null
• listener name must not be blank

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