apache/pulsar · error · RestException

Peer cluster %s data not found

Error message

Peer cluster %s data not found

What it means

HTTP 404 NOT_FOUND raised while validating peer-replication-cluster ownership: a namespace's peer cluster name is listed in peerClusterNames (or the allowed clusters), but no ClusterData record exists for that peer in the cluster configuration store. The broker cannot resolve the peer to route or authorize the request.

Source

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

    private static CompletableFuture<ClusterDataImpl> getOwnerFromPeerClusterListAsync(PulsarService pulsar,
            Set<String> replicationClusters, Set<String> allowedClusters) {
        String currentCluster = pulsar.getConfiguration().getClusterName();
        if (replicationClusters.isEmpty() && allowedClusters.isEmpty() || isBlank(currentCluster)) {
            return CompletableFuture.completedFuture(null);
        }

        return pulsar.getPulsarResources().getClusterResources().getClusterAsync(currentCluster)
                .thenCompose(cluster -> {
                    if (!cluster.isPresent() || cluster.get().getPeerClusterNames() == null) {
                        return CompletableFuture.completedFuture(null);
                    }
                    for (String peerCluster : cluster.get().getPeerClusterNames()) {
                        if (replicationClusters.contains(peerCluster)
                                || allowedClusters.contains(peerCluster)) {
                            return pulsar.getPulsarResources().getClusterResources().getClusterAsync(peerCluster)
                                    .thenApply(ret -> {
                                        if (!ret.isPresent()) {
                                            throw new RestException(Status.NOT_FOUND,
                                                    "Peer cluster " + peerCluster + " data not found");
                                        }
                                        return (ClusterDataImpl) ret.get();
                                    });
                        }
                    }
                    return CompletableFuture.completedFuture(null);
                }).exceptionally(ex -> {
                    LOG.error()
                            .attr("cluster", currentCluster)
                            .exceptionMessage(ex)
                            .log("Failed to get peer-cluster -");
                    throw FutureUtil.wrapToCompletionException(ex);
                });
    }

    protected static CompletableFuture<Void> checkAuthorizationAsync(PulsarService pulsarService, TopicName topicName,
                        String role, String originalPrinciple, AuthenticationDataSource authenticationData,

View on GitHub (pinned to 820761864e)

Solutions

1. Register the missing peer cluster: PUT /admin/v2/clusters/<peerCluster> with valid ClusterData
2. Or remove the dangling peer cluster name from the cluster's peerClusterNames (update the owning cluster's config)
3. Audit all clusters' peerClusterNames against the actual cluster list to find stale references
4. If the namespace should no longer replicate to the peer, remove it from the namespace's replication_clusters

Example fix

// before: dangling peer reference
admin.clusters().updateCluster("west", ClusterData.builder().peerClusterNames(Set.of("gone-east")).build());
// after: only reference registered clusters, or register the peer first
admin.clusters().createCluster("gone-east", ClusterDataImpl.builder()
    .serviceUrl("http://east.example.com:8080").build());

Set<String> registered = admin.clusters().getClusters();
for (String peer : admin.clusters().getCluster(owner).getPeerClusterNames()) {
    if (!registered.contains(peer)) throw new IllegalStateException("dangling peer cluster: " + peer);
}

boolean peerClustersExist(ClusterData cd, Set<String> registered) {
    return cd.getPeerClusterNames() == null || registered.containsAll(cd.getPeerClusterNames());
}

When it happens

Trigger: Calling any endpoint that resolves namespace ownership where the namespace's cluster lists a peer cluster in peerClusterNames that was deleted from /admin/v2/clusters, or was never registered.

Common situations: A cluster was deregistered from the configuration store but namespaces still reference it in peerClusterNames; geo-replication setup partially completed; cluster renamed without updating peer lists.

Related errors

• The replication cluster does not provide TLS encrypted servi
• Namespace does not exist
• Cannot delete the global namespace ${nsName}. There are stil
• Cannot delete the global namespace ${namespaceName}. There a
• Partition count mismatch for ${topicType} '${topic}': local

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