apache/pulsar · error · IOException

Failed to bind Pulsar broker on

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.

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.

Appendix: 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)