{"record":{"id":"7d525295989748b1","repo":"apache/pulsar","slug":"peer-cluster-peercluster-does-not-exist","errorCode":null,"errorMessage":"Peer cluster ${peerCluster} does not exist","messagePattern":"Peer cluster (.+?) does not exist","errorType":"http","errorClass":"RestException","httpStatus":412,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/ClustersBase.java","lineNumber":432,"sourceCode":"                    return null;\n                });\n\n    }\n\n    private CompletableFuture<Void> innerSetPeerClusterNamesAsync(String cluster,\n                                                                LinkedHashSet<String> peerClusterNames) {\n        // validate if peer-cluster exist\n        CompletableFuture<Void> future;\n        if (CollectionUtils.isNotEmpty(peerClusterNames)) {\n            future = FutureUtil.waitForAll(peerClusterNames.stream().map(peerCluster -> {\n                if (cluster.equalsIgnoreCase(peerCluster)) {\n                    return FutureUtil.failedFuture(new RestException(PRECONDITION_FAILED,\n                            cluster + \" itself can't be part of peer-list\"));\n                }\n                return clusterResources().getClusterAsync(peerCluster)\n                        .thenAccept(peerClusterOpt -> {\n                            if (!peerClusterOpt.isPresent()) {\n                                throw new RestException(PRECONDITION_FAILED,\n                                        \"Peer cluster \" + peerCluster + \" does not exist\");\n                            }\n                        });\n            }).collect(Collectors.toList()));\n        } else {\n            future = CompletableFuture.completedFuture(null);\n        }\n        return future.thenCompose(__ -> clusterResources().updateClusterAsync(cluster,\n                old -> old.clone().peerClusterNames(peerClusterNames).build()));\n    }\n\n    @GET\n    @Path(\"/{cluster}/peers\")\n    @Operation(\n            summary = \"Get the peer-cluster data for the specified cluster.\",\n            description = \"This operation requires Pulsar superuser privileges.\"\n    )\n    @ApiResponses(value = {","sourceCodeStart":414,"sourceCodeEnd":450,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/ClustersBase.java#L414-L450","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Create the missing peer cluster first via POST /admin/v3/clusters/{peerCluster} with correct ClusterData (service URLs).","List existing clusters with GET /admin/v3/clusters and correct the peer list to match exact existing names (names are case-sensitive).","Remove the nonexistent entry from the peerClusterNames array and re-submit.","If the peer was renamed, update to the new name rather than the historical one."],"exampleFix":"// before\nadmin.clusters().updatePeerClusterNames(\"us-west\", List.of(\"us-east-typo\")); // 412\n// after\nList<String> existing = admin.clusters().getClusters();\nList<String> peers = List.of(\"us-east\").stream()\n        .filter(existing::contains).collect(Collectors.toList());\nadmin.clusters().updatePeerClusterNames(\"us-west\", peers);","handlingStrategy":"validation","validationCode":"Set<String> existing = new HashSet<>(admin.clusters().getClusters());\nList<String> invalid = peerClusterNames.stream()\n        .filter(p -> !existing.contains(p))\n        .collect(Collectors.toList());\nif (!invalid.isEmpty()) {\n    throw new IllegalArgumentException(\"Peer clusters not found: \" + invalid);\n}\nadmin.clusters().updatePeerClusterNames(cluster, peerClusterNames);","typeGuard":null,"tryCatchPattern":"try {\n    admin.clusters().updatePeerClusterNames(cluster, names);\n} catch (PulsarAdminException.PreconditionFailedException e) {\n    // message names the missing peer cluster: create it or fix the name\n    throw new IllegalStateException(\"Fix peer cluster names before retry: \" + e.getMessage(), e);\n}","preventionTips":["Provision all peer clusters before wiring peer relationships.","Validate peer names against GET /admin/v3/clusters in CI before applying config.","Remember names are case-sensitive; centralize cluster-name constants."],"tags":["rest-api","peer-cluster","validation","replication"],"backgroundTag":"referenced-resource-not-found","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}