apache/pulsar · error · IOException

Failed to bind Pulsar broker on ${addr}

Error message

Failed to bind Pulsar broker on ${addr}

What it means

Startup binding failure in BrokerService: the Netty server channel for the given bind address (listenChannel/listenChannelTls selection path) could not be established or the expected bound channel for that address is absent, so the broker cannot serve on that listener; usually a port-in-use or invalid bind address problem surfaced while starting the broker.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/BrokerService.java:696

                // identify the primary channel. Note that the legacy bindings appear first and have no listener.
                if (StringUtils.isBlank(a.getListenerName())
                        || StringUtils.equalsIgnoreCase(a.getListenerName(), internalListenerName)) {
                    if (this.listenChannel == null && !isTls) {
                        this.listenChannel = ch;
                    }
                    if (this.listenChannelTls == null && isTls) {
                        this.listenChannelTls = ch;
                    }
                }

                log.info()
                        .attr("localAddress", ch.localAddress())
                        .attr("tls", isTls ? SslContext.defaultServerProvider().toString() : "(none)")
                        .attr("listener", StringUtils.defaultString(a.getListenerName(), "(none)"))
                        .log("Started Pulsar Broker service");
            } catch (Exception e) {
                throw new IOException("Failed to bind Pulsar broker on " + addr, e);
            }
        }

        // start other housekeeping functions
        this.startStatsUpdater(
                serviceConfig.getStatsUpdateInitialDelayInSecs(),
                serviceConfig.getStatsUpdateFrequencyInSecs());
        this.initializeHealthChecker();
        this.startInactivityMonitor();
        this.startMessageExpiryMonitor();
        this.startCompactionMonitor();
        this.startConsumedLedgersMonitor();
        this.startBacklogQuotaChecker();
        this.startSubscriptionBacklogAgeChecker();
        this.updateBrokerPublisherThrottlingMaxRate();
        this.updateBrokerDispatchThrottlingMaxRate();
        this.startCheckReplicationPolicies();
        this.startDeduplicationSnapshotMonitor();

View on GitHub (pinned to 820761864e)

Solutions

1. Stop the process occupying the port or change the broker port
2. Check bind address validity and firewall/permission settings, then restart

When it happens

Trigger: Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/BrokerService.java:696 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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