{"record":{"id":"3bdaa52657440dd3","repo":"apache/pulsar","slug":"failed-to-bind-protocol-protocol-on-address","errorCode":null,"errorMessage":"Failed to bind protocol `${protocol}` on ${address}","messagePattern":"Failed to bind protocol `(.+?)` on (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/service/BrokerService.java","lineNumber":611,"sourceCode":"            bootstrap.childOption(ChannelOption.TCP_NODELAY, true);\n            bootstrap.childOption(ChannelOption.RCVBUF_ALLOCATOR,\n                    new AdaptiveRecvByteBufAllocator(1024, 16 * 1024, 1 * 1024 * 1024));\n            EventLoopUtil.enableTriggeredMode(bootstrap);\n            DefaultThreadFactory defaultThreadFactory =\n                    new ExecutorProvider.ExtendedThreadFactory(\"pulsar-ph-\" + protocol);\n            EventLoopGroup dedicatedWorkerGroup =\n                    EventLoopUtil.newEventLoopGroup(configuration.getNumIOThreads(), false, defaultThreadFactory);\n            bootstrap.channel(EventLoopUtil.getServerSocketChannelClass(dedicatedWorkerGroup));\n            protocolHandlersWorkerGroups.add(Pair.of(protocol, dedicatedWorkerGroup));\n            bootstrap.group(this.acceptorGroup, dedicatedWorkerGroup);\n        } else {\n            bootstrap = defaultServerBootstrap.clone();\n        }\n        bootstrap.childHandler(initializer);\n        try {\n            bootstrap.bind(address).sync();\n        } catch (Exception e) {\n            throw new IOException(\"Failed to bind protocol `\" + protocol + \"` on \" + address, e);\n        }\n        log.info().attr(\"protocol\", protocol).attr(\"address\", address).log(\"Successfully bind protocol `` on\");\n    }\n\n    private ServerBootstrap defaultServerBootstrap() {\n        ServerBootstrap bootstrap = new ServerBootstrap();\n        bootstrap.option(ChannelOption.SO_REUSEADDR, true);\n        bootstrap.childOption(ChannelOption.ALLOCATOR, PulsarByteBufAllocator.DEFAULT);\n        bootstrap.group(acceptorGroup, workerGroup);\n        bootstrap.childOption(ChannelOption.TCP_NODELAY, true);\n        bootstrap.childOption(ChannelOption.RCVBUF_ALLOCATOR,\n            new AdaptiveRecvByteBufAllocator(1024, 16 * 1024, 1 * 1024 * 1024));\n        bootstrap.channel(EventLoopUtil.getServerSocketChannelClass(workerGroup));\n        EventLoopUtil.enableTriggeredMode(bootstrap);\n        return bootstrap;\n    }\n\n    public Map<String, TopicStatsImpl> getTopicStats(NamespaceBundle bundle) {","sourceCodeStart":593,"sourceCodeEnd":629,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/service/BrokerService.java#L593-L629","documentation":"startProtocolHandler failed to bind the network listener for the given protocol on its configured address (port already in use or bind failure); the protocol handler cannot start and broker startup fails.","triggerScenarios":"Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/BrokerService.java:611 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Free the occupied port or change the protocol handler's port configuration","Verify bind addresses/permissions, then restart the broker"],"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-14T00:17:10.932Z"}