apache/pulsar · error · RestException

Exist unexpected topic partition(partition index grater than

Error message

Exist unexpected topic partition(partition index grater than current metadata maximum index %s) %s 

What it means

During partition expansion the broker found an existing topic partition whose index is beyond the current metadata's maximum index — an inconsistent leftover partition, usually from a previously failed update.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/PersistentTopicsBase.java:426

                            .thenAccept(topics -> {
                                final List<TopicName> existingPartitions = topics.stream()
                                        .map(TopicName::get)
                                        .filter(candidateTopicName -> candidateTopicName.getPartitionedTopicName()
                                                .equals(topicName.getPartitionedTopicName()))
                                        .collect(Collectors.toList());
                                    // Check whether exist unexpected partition
                                    Optional<Integer> maximumPartitionIndex = existingPartitions.stream()
                                            .map(TopicName::getPartitionIndex)
                                            .max(Integer::compareTo);
                                    if (maximumPartitionIndex.isPresent()
                                            && maximumPartitionIndex.get() >= currentMetadataPartitions) {
                                        List<String> unexpectedPartitions = existingPartitions.stream()
                                                .filter(candidateTopicName ->
                                                        candidateTopicName
                                                                .getPartitionIndex() > currentMetadataPartitions)
                                                .map(TopicName::toString)
                                                .collect(Collectors.toList());
                                        throw new RestException(Status.CONFLICT,
                                                String.format(
                                                        "Exist unexpected topic partition(partition index grater than"
                                                                + " current metadata maximum index %s) %s ",
                                                        currentMetadataPartitions,
                                                        StringUtils.join(unexpectedPartitions, ",")));
                                    }
                            });
                } else {
                    checkFuture = CompletableFuture.completedFuture(null);
                }
                return checkFuture.thenCompose(topics -> {
                    final CompletableFuture<Void> updateMetadataFuture = (expectPartitions == currentMetadataPartitions)
                            // current metadata partitions is equals to expect partitions
                            ? CompletableFuture.completedFuture(null)
                            // update current cluster topic metadata
                            : namespaceResources().getPartitionedTopicResources()
                            .updatePartitionedTopicAsync(topicName, m ->
                                    new PartitionedTopicMetadata(expectPartitions, m.properties));

View on GitHub (pinned to 820761864e)

Solutions

1. Delete the orphaned high-index partitions and retry the update
2. Use the force flag if available to proceed despite the inconsistency

When it happens

Trigger: Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/PersistentTopicsBase.java:426 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/7c4d97fe69ab2c2f. Report an issue: GitHub.