apache/pulsar · error · PulsarServerException

No active broker is available

Error message

No active broker is available

What it means

nextBroker() fetches the cached list of active brokers from the metadata store; when that list is empty it cannot do round-robin selection and throws PulsarServerException('No active broker is available'). The proxy is running but no broker has registered itself in the load manager reports yet.

Source

Thrown at pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/BrokerDiscoveryProvider.java:90

     * Used by Protocol Handlers
     * @return the list of available brokers
     * @throws PulsarServerException
     */
    public List<? extends ServiceLookupData> getAvailableBrokers() throws PulsarServerException {
        return metadataStoreCacheLoader.getAvailableBrokers();
    }

    /**
     * Find next broker {@link LoadManagerReport} in round-robin fashion.
     *
     * @return
     * @throws PulsarServerException
     */
    LoadManagerReport nextBroker() throws PulsarServerException {
        List<LoadManagerReport> availableBrokers = metadataStoreCacheLoader.getAvailableBrokers();

        if (availableBrokers.isEmpty()) {
            throw new PulsarServerException("No active broker is available");
        } else {
            int brokersCount = availableBrokers.size();
            int nextIdx = signSafeMod(counter.getAndIncrement(), brokersCount);
            return availableBrokers.get(nextIdx);
        }
    }

    @Override
    public void close() throws IOException {
        metadataStoreCacheLoader.close();
        orderedExecutor.shutdown();
        scheduledExecutorScheduler.shutdownNow();
    }

}

View on GitHub (pinned to 820761864e)

Solutions

1. Verify brokers are up and registered (check /loadbalance/brokers in ZooKeeper or the equivalent metadata path)
2. Confirm the proxy's metadataStoreUrl points to the same cluster as the brokers
3. Restart or scale up the broker cluster if all brokers are down
4. Retry the client operation once brokers register; the list is refreshed by the cache loader

Example fix

// before: proxy pointed at dev cluster metadata
cluster1: metadataStoreUrl=zk:dev-zk:2181
// after: point proxy at the production cluster hosting brokers
cluster1: metadataStoreUrl=zk:prod-zk-1:2181,prod-zk-2:2181

// Before issuing discovery requests, check broker registrations exist
List<LoadManagerReport> brokers = discoveryProvider.getAvailableBrokers();
if (brokers == null || brokers.isEmpty()) {
    throw new ServiceUnavailableException("No brokers registered yet; retry later");
}

try { LoadManagerReport b = provider.nextBroker(); } catch (PulsarServerException e) {
    if ("No active broker is available".equals(e.getMessage())) {
        // exponential backoff retry; broker may still be registering
    }
}

When it happens

Trigger: Calling nextBroker() (discovery lookup path for proxy -> broker routing) while metadataStoreCacheLoader.getAvailableBrokers() returns an empty list — no broker load reports present in the metadata store cache.

Common situations: All brokers down or still starting; proxy pointed at the wrong ZooKeeper/metadata-store namespace so it sees no broker registrations; network partition between proxy and broker cluster; cache loader session timeout causing a temporarily empty view.

Related errors

• Metadata path must start with '${WELL_KNOWN_PREFIX}', but wa
• Cannot obtain authorization metadata from ${metadataUrl}
• No usable leader URL (useTls=<tls>, url=<url>, urlTls=<urlTl
• Failed to load the extension for extension name `${extension
• Malformed extension found for extension name `${extensionNam

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/0285d90a65d4841a. Report an issue: GitHub.