apache/pulsar · error · org.apache.pulsar.broker.admin.RestException

Cluster ${cluster} does not exist.

Error message

Cluster ${cluster} does not exist.

What it means

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.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/AdminResource.java:494

        // validates global-namespace contains local/peer cluster: if peer/local cluster present then lookup can
        // serve/redirect request else fail partitioned-metadata-request so, client fails while creating
        // producer/consumer
        return validateTopicOperationAsync(topicName, TopicOperation.LOOKUP)
                .thenCompose(__ -> validateGlobalNamespaceOwnershipAsync(topicName.getNamespaceObject()))
                .thenCompose(__ -> {
                    if (checkAllowAutoCreation) {
                        return pulsar().getBrokerService()
                                .fetchPartitionedTopicMetadataCheckAllowAutoCreationAsync(topicName);
                    } else {
                        return pulsar().getBrokerService().fetchPartitionedTopicMetadataAsync(topicName);
                    }
                });
    }

    protected CompletableFuture<Void> validateClusterExistsAsync(String cluster) {
        return clusterResources().clusterExistsAsync(cluster).thenAccept(clusterExist -> {
            if (!clusterExist) {
                throw new RestException(Status.PRECONDITION_FAILED, "Cluster " + cluster + " does not exist.");
            }
        });
    }

    /**
     * Directly get the replication clusters for a namespace, without checking allowed clusters.
     */
    protected CompletableFuture<Set<String>> getNamespaceReplicatedClustersAsync(NamespaceName namespaceName) {
        return namespaceResources().getPoliciesAsync(namespaceName)
                .thenApply(policies -> {
                    if (policies.isPresent()) {
                        return policies.get().replication_clusters;
                    } else {
                        throw new RestException(Status.NOT_FOUND, "Namespace does not exist");
                    }
                });
    }

View on GitHub (pinned to 820761864e)

Solutions

1. List existing clusters (GET /admin/v2/clusters) and confirm the exact spelling of the target cluster.
2. Register the missing cluster with PUT /admin/v2/clusters/<cluster> if it genuinely should exist.
3. Correct the cluster name in your namespace replication policy or request.
4. After registering a new cluster, verify the config-store propagation before re-running the operation.

Example fix

// before
admin.namespaces().setNamespaceReplicationClusters("my-tenant/my-ns",
        Sets.newHashSet("use-east")); // typo
// after
admin.namespaces().setNamespaceReplicationClusters("my-tenant/my-ns",
        Sets.newHashSet("us-east"));

// Java: verify the cluster exists before referencing it
Set<String> clusters = admin.clusters().getClusters();
if (!clusters.contains("us-east")) {
    admin.clusters().createCluster("us-east",
        new ClusterData(UriBuilder.fromUri("pulsar://us-east-broker:6650").build()));
}

static boolean clusterKnown(Set<String> clusters, String name) {
    return name != null && clusters.contains(name);
}

try {
    admin.namespaces().setNamespaceReplicationClusters(ns, newClusters);
} catch (PulsarAdminException e) {
    if (e.getStatusCode() == 412 && e.getMessage().contains("does not exist")) {
        // create the missing cluster or fix the name
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Broker is forbidden to do read-write operations
• Topic name is not valid
• Partitioned Topic Name should not contain '-partition-'
• Exceed maximum number of topics in namespace.
• Backlog Quota exceeds configured retention quota for namespa

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