apache/pulsar · error · RestException

Partition count mismatch for ${topicType} '${topic}': local

Error message

Partition count mismatch for ${topicType} '${topic}': local cluster has ${localPartitions} partitions, remote cluster '${remoteCluster}' has ${remotePartitions} partitions. Please ensure partition counts are the same before enabling replication.

What it means

This 409 CONFLICT is thrown during namespace replication validation when a system topic (e.g. the __change_events or topic-policies system topic) exists locally and on the remote cluster but with different partition counts. Geo-replication of namespace/system topics requires matching partition counts, so enabling or validating replication is refused.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/NamespacesBase.java:1149

                                    || ex instanceof PulsarAdminException.NotFoundException) {
                                return Optional.empty();
                            }
                            throw new CompletionException(ex);
                        });

        return localMetadataFuture.thenCombine(remoteMetadataFuture, (localMetadataOpt, remoteMetadataOpt) -> {
            // If topic doesn't exist on remote, validation passes
            if (remoteMetadataOpt.isEmpty()) {
                return null;
            }

            int localPartitions = localMetadataOpt.map(m -> m.partitions).orElse(0);
            int remotePartitions = remoteMetadataOpt.get().partitions;

            if (localPartitions != remotePartitions) {
                String topicType = SystemTopicNames.isTopicPoliciesSystemTopic(topic)
                        ? "__change_events system topic" : "topic";
                throw new RestException(Status.CONFLICT,
                        String.format("Partition count mismatch for %s '%s': local cluster has %d partitions, "
                                        + "remote cluster '%s' has %d partitions. "
                                        + "Please ensure partition counts are the same before enabling replication.",
                                topicType, topic, localPartitions, remoteCluster, remotePartitions));
            }
            return null;
        });
    }

    /**
     * Validates that the effective auto-topic creation policies are the same between local and remote clusters.
     * The effective policy is computed by: namespace-level policy overrides broker-level if it exists.
     */
    private CompletableFuture<Void> validateAutoTopicCreationCompatibility(PulsarAdmin remoteAdmin,
                                                                    String remoteCluster, Policies remoteNsPolicies) {
        String namespaceStr = namespaceName.toString();

        // Get local broker config

View on GitHub (pinned to 820761864e)

Solutions

1. Compare partition counts on both clusters (GET /admin/v2/persistent/{tenant}/{ns}/{topic}/partitions) and recreate the topic on one cluster with the matching count
2. Delete and recreate the mismatched topic on the remote cluster with the local partition count before enabling replication
3. Align broker.conf defaultNumberOfBrokerPartitions across clusters so future topics match automatically
4. If it's a system topic, ensure both clusters run compatible Pulsar versions and the namespace policy that controls system topic partitions is identical

Example fix

// before: local 8 partitions, remote created with 4
// remote cluster:
admin.topics().deletePartitionedTopic("persistent://my-tenant/my-ns/__change_events");
admin.topics().createPartitionedTopic("persistent://my-tenant/my-ns/__change_events", 8);
// after: both clusters have 8 partitions, replication validation passes

int local = admin.topics().getPartitionedTopicMetadata(topic).partitions;
int remote = remoteAdmin.topics().getPartitionedTopicMetadata(topic).partitions;
if (local != remote) throw new IllegalStateException("Partition mismatch: " + local + " vs " + remote);

try {
    admin.namespaces().setNamespaceReplicationClusters(ns, clusters);
} catch (PulsarAdminException.ConflictException e) {
    // reconcile topic partition counts across clusters
}

When it happens

Trigger: Enabling replication (or setting replication clusters) for a namespace whose system/partitioned topic has N partitions locally while the same topic on the remote cluster has M != N partitions.

Common situations: Topic was created with different defaultNumberOfBrokerPartitions on each cluster; an operator manually created the topic with createPartitionedTopic using different counts per cluster; bumping partitions on only one cluster (increasePartitions) before enabling replication.

Related errors

• Effective auto-topic creation policy mismatch for namespace
• Partitioned Topic Name should not contain '-partition-'
• Topic is not partitioned topic
• Exceed maximum number of topics in namespace.
• This topic already exists

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