apache/pulsar · error · IllegalArgumentException

At least one broker bind address must be configured

Error message

At least one broker bind address must be configured

What it means

BrokerService startup validation found no bind address configured: neither the advertised address nor any listener provides an address to bind the server socket to, so the broker cannot open its listeners.

Source

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

        this.producerNameGenerator = new DistributedIdGenerator(pulsar.getCoordinationService(),
                PRODUCER_NAME_GENERATOR_PATH, pulsar.getConfiguration().getClusterName());

        // Initialize scalable topic service
        var scalableTopicResources = pulsar.getPulsarResources().getScalableTopicResources();
        if (scalableTopicResources != null) {
            this.scalableTopicService = new org.apache.pulsar.broker.service.scalable.ScalableTopicService(
                    this, scalableTopicResources, pulsar.getCoordinationService());
            this.scalableTopicService.start();
        }

        ServiceConfiguration serviceConfig = pulsar.getConfiguration();
        List<BindAddress> bindAddresses = BindAddressValidator.validateBindAddresses(serviceConfig,
                Arrays.asList("pulsar", "pulsar+ssl"));
        String internalListenerName = serviceConfig.getInternalListenerName();

        // create a channel for each bind address
        if (bindAddresses.size() == 0) {
            throw new IllegalArgumentException("At least one broker bind address must be configured");
        }
        for (BindAddress a : bindAddresses) {
            InetSocketAddress addr = new InetSocketAddress(a.getAddress().getHost(), a.getAddress().getPort());
            boolean isTls = "pulsar+ssl".equals(a.getAddress().getScheme());
            PulsarChannelInitializer.PulsarChannelOptions opts = PulsarChannelInitializer.PulsarChannelOptions.builder()
                            .enableTLS(isTls)
                            .listenerName(a.getListenerName()).build();

            ServerBootstrap b = defaultServerBootstrap.clone();
            PulsarChannelInitializer channelInitializer =
                    pulsarChannelInitFactory.newPulsarChannelInitializer(pulsar, opts);
            pulsarChannelInitializers.add(channelInitializer);
            b.childHandler(channelInitializer);
            try {
                Channel ch = b.bind(addr).sync().channel();
                listenChannels.add(ch);

                // identify the primary channel. Note that the legacy bindings appear first and have no listener.

View on GitHub (pinned to 820761864e)

Solutions

1. Set advertisedListeners/bindAddresses in broker.conf
2. Fix malformed listener definitions and restart

When it happens

Trigger: Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/BrokerService.java:661 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/961cc15a505ba503. Report an issue: GitHub.