apache/pulsar · error · RestException

Broker id '${brokerId}' not found in available brokers.

Error message

Broker id '${brokerId}' not found in available brokers.

What it means

Admin redirect guard in maybeRedirectToBroker: the supplied broker id (lookup service address) matches neither this broker's id nor any registered broker in the cluster, so the request can neither be served locally nor forwarded; typically a stale or mistyped broker address from client-side discovery data.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/web/PulsarWebResource.java:1204

     *
     * @param brokerId broker's id (lookup service address)
     */
    protected CompletableFuture<Void> maybeRedirectToBroker(String brokerId) {
        // backwards compatibility
        String cleanedBrokerId = brokerId.replaceFirst("http[s]?://", "");
        if (pulsar.getBrokerId().equals(cleanedBrokerId)
                // backwards compatibility
                || ("http://" + cleanedBrokerId).equals(pulsar().getWebServiceAddress())
                || ("https://" + cleanedBrokerId).equals(pulsar().getWebServiceAddressTls())) {
            // no need to redirect, the current broker matches the given broker id
            return CompletableFuture.completedFuture(null);
        }
        LockManager<BrokerLookupData> brokerLookupDataLockManager =
                pulsar().getCoordinationService().getLockManager(BrokerLookupData.class);
        return brokerLookupDataLockManager.readLock(LoadManager.LOADBALANCE_BROKERS_ROOT + "/" + cleanedBrokerId)
                .thenAccept(brokerLookupDataOptional -> {
                    if (brokerLookupDataOptional.isEmpty()) {
                        throw new RestException(Status.NOT_FOUND,
                                "Broker id '" + brokerId + "' not found in available brokers.");
                    }
                    brokerLookupDataOptional.ifPresent(brokerLookupData -> {
                        URI targetBrokerUri;
                        if ((isRequestHttps() || StringUtils.isBlank(brokerLookupData.getWebServiceUrl()))
                                && StringUtils.isNotBlank(brokerLookupData.getWebServiceUrlTls())) {
                            targetBrokerUri = URI.create(brokerLookupData.getWebServiceUrlTls());
                        } else {
                            targetBrokerUri = URI.create(brokerLookupData.getWebServiceUrl());
                        }
                        URI redirect = UriBuilder.fromUri(uri.getRequestUri())
                                .scheme(targetBrokerUri.getScheme())
                                .host(targetBrokerUri.getHost())
                                .port(targetBrokerUri.getPort()).build();
                        log.debug()
                                .attr("redirect", redirect)
                                .attr("broker", cleanedBrokerId)
                                .log("Redirecting the rest call");

View on GitHub (pinned to 820761864e)

Solutions

1. Retry against an active broker (lookup will find one)
2. Wait for the dead broker's sessions/ownership to be re-acquired

When it happens

Trigger: Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/web/PulsarWebResource.java:1204 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/b3d447ba94fe163c. Report an issue: GitHub.