apache/pulsar · error · RestException

Peer cluster ${peerCluster} does not exist

Error message

Peer cluster ${peerCluster} does not exist

What it means

HTTP 412 (PRECONDITION_FAILED) thrown when setting a cluster's peer-cluster list and one of the requested peer cluster names does not exist in cluster metadata. Each name in the list is validated with clusterResources().getClusterAsync; any missing name aborts the whole update. Peer cluster names must reference real, configured clusters for replication.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/ClustersBase.java:432

                    return null;
                });

    }

    private CompletableFuture<Void> innerSetPeerClusterNamesAsync(String cluster,
                                                                LinkedHashSet<String> peerClusterNames) {
        // validate if peer-cluster exist
        CompletableFuture<Void> future;
        if (CollectionUtils.isNotEmpty(peerClusterNames)) {
            future = FutureUtil.waitForAll(peerClusterNames.stream().map(peerCluster -> {
                if (cluster.equalsIgnoreCase(peerCluster)) {
                    return FutureUtil.failedFuture(new RestException(PRECONDITION_FAILED,
                            cluster + " itself can't be part of peer-list"));
                }
                return clusterResources().getClusterAsync(peerCluster)
                        .thenAccept(peerClusterOpt -> {
                            if (!peerClusterOpt.isPresent()) {
                                throw new RestException(PRECONDITION_FAILED,
                                        "Peer cluster " + peerCluster + " does not exist");
                            }
                        });
            }).collect(Collectors.toList()));
        } else {
            future = CompletableFuture.completedFuture(null);
        }
        return future.thenCompose(__ -> clusterResources().updateClusterAsync(cluster,
                old -> old.clone().peerClusterNames(peerClusterNames).build()));
    }

    @GET
    @Path("/{cluster}/peers")
    @Operation(
            summary = "Get the peer-cluster data for the specified cluster.",
            description = "This operation requires Pulsar superuser privileges."
    )
    @ApiResponses(value = {

View on GitHub (pinned to 820761864e)

Solutions

1. Create the missing peer cluster first via POST /admin/v3/clusters/{peerCluster} with correct ClusterData (service URLs).
2. List existing clusters with GET /admin/v3/clusters and correct the peer list to match exact existing names (names are case-sensitive).
3. Remove the nonexistent entry from the peerClusterNames array and re-submit.
4. If the peer was renamed, update to the new name rather than the historical one.

Example fix

// before
admin.clusters().updatePeerClusterNames("us-west", List.of("us-east-typo")); // 412
// after
List<String> existing = admin.clusters().getClusters();
List<String> peers = List.of("us-east").stream()
        .filter(existing::contains).collect(Collectors.toList());
admin.clusters().updatePeerClusterNames("us-west", peers);

Set<String> existing = new HashSet<>(admin.clusters().getClusters());
List<String> invalid = peerClusterNames.stream()
        .filter(p -> !existing.contains(p))
        .collect(Collectors.toList());
if (!invalid.isEmpty()) {
    throw new IllegalArgumentException("Peer clusters not found: " + invalid);
}
admin.clusters().updatePeerClusterNames(cluster, peerClusterNames);

try {
    admin.clusters().updatePeerClusterNames(cluster, names);
} catch (PulsarAdminException.PreconditionFailedException e) {
    // message names the missing peer cluster: create it or fix the name
    throw new IllegalStateException("Fix peer cluster names before retry: " + e.getMessage(), e);
}

When it happens

Trigger: POST /admin/v3/clusters/{cluster}/peers with a peerClusterNames array containing a typo or an unregistered cluster name; referencing a peer that was deleted earlier; configuring replication before provisioning the peer cluster.

Common situations: Cross-region replication setup where the remote cluster wasn't created yet or its name differs in case; YAML config with stale peer names after a peer cluster was decommissioned; copy-paste between environments (dev names used in prod).

Related errors

• ClusterIds should not be null or empty
• Invalid cluster id: ${clusterId}
• cluster data is required
• Cluster ${cluster} does not exist.
• Cluster [${clusterId}] is not in the list of allowed cluster

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