{"record":{"id":"532353ee6ec0e7a6","repo":"apache/pulsar","slug":"failed-to-bind-pulsar-broker-on-addr","errorCode":null,"errorMessage":"Failed to bind Pulsar broker on ${addr}","messagePattern":"Failed to bind Pulsar broker on (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/service/BrokerService.java","lineNumber":696,"sourceCode":"\n                // identify the primary channel. Note that the legacy bindings appear first and have no listener.\n                if (StringUtils.isBlank(a.getListenerName())\n                        || StringUtils.equalsIgnoreCase(a.getListenerName(), internalListenerName)) {\n                    if (this.listenChannel == null && !isTls) {\n                        this.listenChannel = ch;\n                    }\n                    if (this.listenChannelTls == null && isTls) {\n                        this.listenChannelTls = ch;\n                    }\n                }\n\n                log.info()\n                        .attr(\"localAddress\", ch.localAddress())\n                        .attr(\"tls\", isTls ? SslContext.defaultServerProvider().toString() : \"(none)\")\n                        .attr(\"listener\", StringUtils.defaultString(a.getListenerName(), \"(none)\"))\n                        .log(\"Started Pulsar Broker service\");\n            } catch (Exception e) {\n                throw new IOException(\"Failed to bind Pulsar broker on \" + addr, e);\n            }\n        }\n\n        // start other housekeeping functions\n        this.startStatsUpdater(\n                serviceConfig.getStatsUpdateInitialDelayInSecs(),\n                serviceConfig.getStatsUpdateFrequencyInSecs());\n        this.initializeHealthChecker();\n        this.startInactivityMonitor();\n        this.startMessageExpiryMonitor();\n        this.startCompactionMonitor();\n        this.startConsumedLedgersMonitor();\n        this.startBacklogQuotaChecker();\n        this.startSubscriptionBacklogAgeChecker();\n        this.updateBrokerPublisherThrottlingMaxRate();\n        this.updateBrokerDispatchThrottlingMaxRate();\n        this.startCheckReplicationPolicies();\n        this.startDeduplicationSnapshotMonitor();","sourceCodeStart":678,"sourceCodeEnd":714,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/service/BrokerService.java#L678-L714","documentation":"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.","triggerScenarios":"Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/BrokerService.java:696 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Stop the process occupying the port or change the broker port","Check bind address validity and firewall/permission settings, then restart"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"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"}