apache/pulsar · error · RestException

Effective auto-topic creation policy mismatch for namespace

Error message

Effective auto-topic creation policy mismatch for namespace '${namespaceStr}' between local cluster and remote cluster '${remoteCluster}': ${mismatches}. Please ensure auto-topic creation policies are the same before enabling replication.

What it means

This 409 CONFLICT is thrown when validating replication compatibility between two clusters for a namespace: the effective auto-topic-creation policy (allowAutoTopicCreation and/or defaultNumPartitions) differs between local and remote. Geo-replication requires consistent auto-topic creation settings so topics are created identically on both sides.

Source

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

                        remoteEffectiveTopicType = remoteBrokerAutoCreationType.toString();
                        remoteEffectiveDefaultPartitions = remoteBrokerDefaultPartitions;
                    }

                    // Compare effective policies (only topicType and defaultNumPartitions)
                    List<String> mismatches = new ArrayList<>();
                    if (!Objects.equals(localEffectiveTopicType, remoteEffectiveTopicType)) {
                        mismatches.add(String.format("topicType: local=%s, remote=%s",
                                localEffectiveTopicType, remoteEffectiveTopicType));
                    }
                    // Pulsar does not allow to set a special partition count with non-partitioned topic type, comparing
                    // default topic count either default topic type is partitioned or non-partitioned.
                    if (localEffectiveDefaultPartitions != remoteEffectiveDefaultPartitions) {
                        mismatches.add(String.format("defaultNumPartitions: local=%d, remote=%d",
                                localEffectiveDefaultPartitions, remoteEffectiveDefaultPartitions));
                    }

                    if (!mismatches.isEmpty()) {
                        throw new RestException(Status.CONFLICT,
                                String.format("Effective auto-topic creation policy mismatch for namespace '%s' "
                                                + "between local cluster and remote cluster '%s': %s. "
                                                + "Please ensure auto-topic creation policies are the same "
                                                + "before enabling replication.",
                                        namespaceStr, remoteCluster, String.join("; ", mismatches)));
                    }
                });
    }

    protected CompletableFuture<Void> internalSetNamespaceMessageTTLAsync(Integer messageTTL) {
        return validateNamespacePolicyOperationAsync(namespaceName, PolicyName.TTL, PolicyOperation.WRITE)
                .thenCompose(__ -> validatePoliciesReadOnlyAccessAsync())
                .thenAccept(__ -> {
                    if (messageTTL != null && messageTTL < 0) {
                        throw new RestException(Status.PRECONDITION_FAILED,
                                "Invalid value for message TTL, message TTL must >= 0");
                    }
                }).thenCompose(__ -> updatePoliciesAsync(namespaceName, policies -> {

View on GitHub (pinned to 820761864e)

Solutions

Set the same autoTopicCreationOverride on the namespace in both clusters via admin.namespaces().setAutoTopicCreationAsync(...)
If no namespace override is intended, align broker.conf allowAutoTopicCreation and defaultNumberOfBrokerPartitions on all clusters
Read the mismatches detail in the error message (allowAutoTopicCreation / defaultNumPartitions) to see exactly which field differs and fix that field
Re-run validation after applying the policy so cached metadata is refreshed

Example fix

// before: override only set on local cluster
admin.namespaces().setAutoTopicCreation("my-tenant/my-ns",
    AutoTopicCreationOverride.builder().allowAutoTopicCreation(true)
        .topicType("partitioned").defaultNumPartitions(4).build());
// after: apply the identical override on the remote cluster too
remoteAdmin.namespaces().setAutoTopicCreation("my-tenant/my-ns",
    AutoTopicCreationOverride.builder().allowAutoTopicCreation(true)
        .topicType("partitioned").defaultNumPartitions(4).build());

Defensive patterns

Strategy: validation

Validate before calling

AutoTopicCreationOverride local = admin.namespaces().getAutoTopicCreation(ns);
AutoTopicCreationOverride remote = remoteAdmin.namespaces().getAutoTopicCreation(ns);
if (!Objects.equals(local, remote)) throw new IllegalStateException("autoTopicCreationOverride differs across clusters");

Try / catch

try {
    admin.namespaces().setNamespaceReplicationClusters(ns, clusters);
} catch (PulsarAdminException.ConflictException e) {
    // align auto-topic-creation policy, then retry
}

Prevention

Apply namespace policy changes to all peer clusters in the same deployment step
Keep broker auto-topic-creation defaults consistent across datacenters
Diff namespace policies across clusters before enabling replication

When it happens

Trigger: Enabling or validating replication for a namespace where one cluster has allowAutoTopicCreation=true and the other false, or the effective defaultNumPartitions (namespace override falling back to broker default) differs between the clusters.

Common situations: Namespace-level autoTopicCreationOverride set on one cluster but not the peer; broker.conf allowAutoTopicCreation or defaultNumberOfPartitionsForNonPartitionedTopics / defaultNumberOfBrokerPartitions differ between datacenters; a namespace was replicated before the policy changed on one cluster.

Related errors

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