apache/pulsar · error · RestException

Could not examine messages due to the total message is zero

Error message

Could not examine messages due to the total message is zero

What it means

Internal examination guard in PersistentTopicsBase: the message-examination (peek/skip) path refuses to proceed because the topic's total message count reported by the managed ledger is zero, so there is nothing to examine; the caller passes a message position that cannot exist on an empty backlog.

Source

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

                                return CompletableFuture.completedFuture(null);
                            }
                        });
            }
            return CompletableFuture.completedFuture(null);
        }).thenCompose(__ -> getTopicReferenceAsync(topicName))
        .thenCompose(topic -> {
            if (!(topic instanceof PersistentTopic)) {
                log.error()
                        .attr("topic", topicName)
                        .log("Not supported operation of non-persistent topic");
                throw new RestException(Status.METHOD_NOT_ALLOWED,
                        "Examine messages on a non-persistent topic is not allowed");
            }
            try {
                PersistentTopic persistentTopic = (PersistentTopic) topic;
                long totalMessage = persistentTopic.getNumberOfEntries();
                if (totalMessage <= 0) {
                    throw new RestException(Status.PRECONDITION_FAILED,
                            "Could not examine messages due to the total message is zero");
                }
                Position startPosition = persistentTopic.getFirstPosition();

                long messageToSkip = initialPositionLocal.equals("earliest") ? messagePositionLocal :
                        totalMessage - messagePositionLocal + 1;
                CompletableFuture<Entry> future = new CompletableFuture<>();
                Position readPosition = persistentTopic.getPositionAfterN(startPosition, messageToSkip);
                persistentTopic.asyncReadEntry(readPosition, new AsyncCallbacks.ReadEntryCallback() {
                    @Override
                    public void readEntryComplete(Entry entry, Object ctx) {
                        future.complete(entry);
                    }

                    @Override
                    public void readEntryFailed(ManagedLedgerException exception, Object ctx) {
                        future.completeExceptionally(exception);
                    }

View on GitHub (pinned to 820761864e)

Solutions

1. Publish messages before calling examine
2. Verify the subscription name — a wrong subscription can also yield no readable entries

When it happens

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