apache/pulsar · error · TopicMigratedException

Topic was already migrated

Error message

Topic was already migrated

What it means

During addProducer, the topic's switch-state check found the topic already migrated to another cluster (part of topic migration); producers cannot attach to a topic whose ownership has moved, so the connection is refused.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/AbstractTopic.java:936

                .getSchemaRegistryService()
                .checkConsumerCompatibility(id, schema, getSchemaCompatibilityStrategy());
    }

    @Override
    public CompletableFuture<Optional<Long>> addProducer(Producer producer,
                                                         CompletableFuture<Void> producerQueuedFuture) {
        checkArgument(producer.getTopic() == this);

        return brokerService.checkTopicNsOwnership(getName())
                .thenCompose(__ ->
                        incrementTopicEpochIfNeeded(producer, producerQueuedFuture))
                .thenCompose(producerEpoch -> {
                    lock.writeLock().lock();
                    try {
                        checkTopicFenced();
                        if (isMigrated()) {
                            log.warn("Attempting to add producer to a migrated topic");
                            throw new TopicMigratedException("Topic was already migrated");
                        } else if (isTerminated()) {
                            log.warn("Attempting to add producer to a terminated topic");
                            throw new TopicTerminatedException("Topic was already terminated");
                        }
                        return internalAddProducer(producer).thenApply(ignore -> {
                            USAGE_COUNT_UPDATER.incrementAndGet(this);
                            log.debug()
                                    .attr("producerName", producer.getProducerName())
                                    .attr("usageCount", USAGE_COUNT_UPDATER.get(this))
                                    .log("Added producer");
                            return producerEpoch;
                        });
                    } catch (BrokerServiceException e) {
                        return FutureUtil.failedFuture(e);
                    } finally {
                        lock.writeLock().unlock();
                    }
                });

View on GitHub (pinned to 820761864e)

Solutions

1. Let the client reconnect — the lookup will be redirected to the new owner
2. Retry after the migration completes

When it happens

Trigger: Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/AbstractTopic.java:936 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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