apache/pulsar · error · RestException

Skip messages on a partitioned topic is not allowed

Error message

Skip messages on a partitioned topic is not allowed

What it means

internalSkipMessages validates the topic type after fetching partition metadata: skipping messages is only supported on a single (non-partitioned) topic partition, so the request against a partitioned topic is rejected with 405 Method Not Allowed.

Source

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

                    return null;
                });
    }

    protected void internalSkipMessages(AsyncResponse asyncResponse, String subName, int numMessages,
                                        boolean authoritative) {
        validateTopicOperationAsync(topicName, TopicOperation.SKIP, subName)
        .thenCompose(__ -> validateGlobalNamespaceOwnershipAsync(namespaceName))
        .thenCompose(__ -> validateTopicOwnershipAsync(topicName, authoritative))
        .thenCompose(__ -> getPartitionedTopicMetadataAsync(topicName, authoritative, false))
        .thenCompose(partitionMetadata -> {
             if (partitionMetadata.partitions > 0) {
                 String msg = "Skip messages on a partitioned topic is not allowed";
                 log.warn()
                         .attr("msg", msg)
                         .attr("topic", topicName)
                         .attr("subscription", subName)
                         .log("");
                 throw new  RestException(Status.METHOD_NOT_ALLOWED, msg);
             }
             return getTopicReferenceAsync(topicName).thenCompose(t -> {
                 PersistentTopic topic = (PersistentTopic) t;
                 if (topic == null) {
                     throw new RestException(new RestException(Status.NOT_FOUND,
                             getTopicNotFoundErrorMessage(topicName.toString())));
                 }
                 if (subName.startsWith(topic.getReplicatorPrefix())) {
                     String remoteCluster = PersistentReplicator.getRemoteCluster(subName);
                     PersistentReplicator repl =
                             (PersistentReplicator) topic.getPersistentReplicator(remoteCluster);
                     if (repl == null) {
                         return FutureUtil.failedFuture(
                                 new RestException(Status.NOT_FOUND, "Replicator not found"));
                     }
                     return repl.skipMessages(numMessages).thenAccept(unused -> {
                         log.info()
                                 .attr("skipped", numMessages)

View on GitHub (pinned to 820761864e)

Solutions

1. Run skip on a specific partition (topic-partition-N)
2. Use reset-cursor or clear-backlog on the partitioned topic for whole-subscription operations

When it happens

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