{"record":{"id":"74a9cd9d0fde7b45","repo":"apache/pulsar","slug":"cluster-cluster-does-not-exist","errorCode":null,"errorMessage":"Cluster ${cluster} does not exist.","messagePattern":"Cluster (.+?) does not exist\\.","errorType":"http","errorClass":"org.apache.pulsar.broker.admin.RestException","httpStatus":412,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/AdminResource.java","lineNumber":494,"sourceCode":"        // validates global-namespace contains local/peer cluster: if peer/local cluster present then lookup can\n        // serve/redirect request else fail partitioned-metadata-request so, client fails while creating\n        // producer/consumer\n        return validateTopicOperationAsync(topicName, TopicOperation.LOOKUP)\n                .thenCompose(__ -> validateGlobalNamespaceOwnershipAsync(topicName.getNamespaceObject()))\n                .thenCompose(__ -> {\n                    if (checkAllowAutoCreation) {\n                        return pulsar().getBrokerService()\n                                .fetchPartitionedTopicMetadataCheckAllowAutoCreationAsync(topicName);\n                    } else {\n                        return pulsar().getBrokerService().fetchPartitionedTopicMetadataAsync(topicName);\n                    }\n                });\n    }\n\n    protected CompletableFuture<Void> validateClusterExistsAsync(String cluster) {\n        return clusterResources().clusterExistsAsync(cluster).thenAccept(clusterExist -> {\n            if (!clusterExist) {\n                throw new RestException(Status.PRECONDITION_FAILED, \"Cluster \" + cluster + \" does not exist.\");\n            }\n        });\n    }\n\n    /**\n     * Directly get the replication clusters for a namespace, without checking allowed clusters.\n     */\n    protected CompletableFuture<Set<String>> getNamespaceReplicatedClustersAsync(NamespaceName namespaceName) {\n        return namespaceResources().getPoliciesAsync(namespaceName)\n                .thenApply(policies -> {\n                    if (policies.isPresent()) {\n                        return policies.get().replication_clusters;\n                    } else {\n                        throw new RestException(Status.NOT_FOUND, \"Namespace does not exist\");\n                    }\n                });\n    }\n","sourceCodeStart":476,"sourceCodeEnd":512,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/AdminResource.java#L476-L512","documentation":"Returned by validateClusterExistsAsync when the cluster name supplied to an admin operation does not exist in the cluster registry (clusterResources().clusterExistsAsync returns false). Indicates a configuration/typo in replication or cluster-scoped operations; returns HTTP 412 Precondition Failed.","triggerScenarios":"Setting a namespace's replication_clusters to a cluster that was never registered (PUT /admin/v2/clusters), or any endpoint validating a `cluster` path parameter (e.g. GET /admin/v2/clusters/<name>/namespaces, peer-cluster setup) with an unregistered name.","commonSituations":"Typo in cluster name ('use-east' vs 'us-east'); cluster registered in one environment but the request targets another; config-store not synced after adding a new cluster; renaming a cluster without updating namespace policies.","solutions":["List existing clusters (GET /admin/v2/clusters) and confirm the exact spelling of the target cluster.","Register the missing cluster with PUT /admin/v2/clusters/<cluster> if it genuinely should exist.","Correct the cluster name in your namespace replication policy or request.","After registering a new cluster, verify the config-store propagation before re-running the operation."],"exampleFix":"// before\nadmin.namespaces().setNamespaceReplicationClusters(\"my-tenant/my-ns\",\n        Sets.newHashSet(\"use-east\")); // typo\n// after\nadmin.namespaces().setNamespaceReplicationClusters(\"my-tenant/my-ns\",\n        Sets.newHashSet(\"us-east\"));","handlingStrategy":"validation","validationCode":"// Java: verify the cluster exists before referencing it\nSet<String> clusters = admin.clusters().getClusters();\nif (!clusters.contains(\"us-east\")) {\n    admin.clusters().createCluster(\"us-east\",\n        new ClusterData(UriBuilder.fromUri(\"pulsar://us-east-broker:6650\").build()));\n}","typeGuard":"static boolean clusterKnown(Set<String> clusters, String name) {\n    return name != null && clusters.contains(name);\n}","tryCatchPattern":"try {\n    admin.namespaces().setNamespaceReplicationClusters(ns, newClusters);\n} catch (PulsarAdminException e) {\n    if (e.getStatusCode() == 412 && e.getMessage().contains(\"does not exist\")) {\n        // create the missing cluster or fix the name\n    }\n}","preventionTips":["Keep a canonical list of cluster names shared by all tooling.","Fetch admin.clusters().getClusters() and validate references before writes.","Watch for cross-environment config leakage (staging vs prod cluster names).","Update namespace replication policies after any cluster rename."],"tags":["http-412","cluster","configuration","admin-api"],"backgroundTag":"unknown-cluster-name","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}