apache/pulsar · error · PulsarServerException

Failed to start the channel.

Error message

Failed to start the channel.

What it means

ServiceUnitStateChannelImpl.start failed while initializing the system-topic-based channel (tableview start, broker registry, session listener registration); the wrapped cause explains which step failed.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/loadbalance/extensions/channel/ServiceUnitStateChannelImpl.java:343

                            pulsar.getConfiguration().getDefaultNumberOfNamespaceBundles());

            tableview = createServiceUnitStateTableView();
            tableview.start(pulsar, this::handleEvent, this::handleExisting, this::handleInvalidate);

            if (debug) {
                log.info("Successfully started the channel tableview.");
            }
            pulsar.getLocalMetadataStore().registerSessionListener(this::handleMetadataSessionEvent);
            if (debug) {
                log.info("Successfully registered the handleMetadataSessionEvent");
            }

            channelState = Started;
            log.info("Successfully started the channel.");
        } catch (Exception e) {
            String msg = "Failed to start the channel.";
            log.error().exception(e).log(msg);
            throw new PulsarServerException(msg, e);
        }
    }

    @VisibleForTesting
    protected BrokerRegistry getBrokerRegistry() {
        return ((ExtensibleLoadManagerWrapper) pulsar.getLoadManager().get())
                .get().getBrokerRegistry();
    }

    @VisibleForTesting
    protected LoadManagerContext getContext() {
        return ((ExtensibleLoadManagerWrapper) pulsar.getLoadManager().get())
                .get().getContext();
    }

    @VisibleForTesting
    protected ExtensibleLoadManagerImpl getLoadManager() {
        return ExtensibleLoadManagerImpl.get(pulsar.getLoadManager().get());

View on GitHub (pinned to 820761864e)

Solutions

1. Check the nested exception for the failing subsystem (metadata store, system topic)
2. Verify the system topic namespace exists and the broker can connect to the metadata store, then restart the broker

When it happens

Trigger: Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/loadbalance/extensions/channel/ServiceUnitStateChannelImpl.java:343 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/4138c87812299202. Report an issue: GitHub.