{"record":{"id":"bd1c440ab103c02a","repo":"apache/pulsar","slug":"could-not-examine-messages-due-to-the-total-messag","errorCode":null,"errorMessage":"Could not examine messages due to the total message is zero","messagePattern":"Could not examine messages due to the total message is zero","errorType":"http","errorClass":"RestException","httpStatus":412,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/PersistentTopicsBase.java","lineNumber":3161,"sourceCode":"                                return CompletableFuture.completedFuture(null);\n                            }\n                        });\n            }\n            return CompletableFuture.completedFuture(null);\n        }).thenCompose(__ -> getTopicReferenceAsync(topicName))\n        .thenCompose(topic -> {\n            if (!(topic instanceof PersistentTopic)) {\n                log.error()\n                        .attr(\"topic\", topicName)\n                        .log(\"Not supported operation of non-persistent topic\");\n                throw new RestException(Status.METHOD_NOT_ALLOWED,\n                        \"Examine messages on a non-persistent topic is not allowed\");\n            }\n            try {\n                PersistentTopic persistentTopic = (PersistentTopic) topic;\n                long totalMessage = persistentTopic.getNumberOfEntries();\n                if (totalMessage <= 0) {\n                    throw new RestException(Status.PRECONDITION_FAILED,\n                            \"Could not examine messages due to the total message is zero\");\n                }\n                Position startPosition = persistentTopic.getFirstPosition();\n\n                long messageToSkip = initialPositionLocal.equals(\"earliest\") ? messagePositionLocal :\n                        totalMessage - messagePositionLocal + 1;\n                CompletableFuture<Entry> future = new CompletableFuture<>();\n                Position readPosition = persistentTopic.getPositionAfterN(startPosition, messageToSkip);\n                persistentTopic.asyncReadEntry(readPosition, new AsyncCallbacks.ReadEntryCallback() {\n                    @Override\n                    public void readEntryComplete(Entry entry, Object ctx) {\n                        future.complete(entry);\n                    }\n\n                    @Override\n                    public void readEntryFailed(ManagedLedgerException exception, Object ctx) {\n                        future.completeExceptionally(exception);\n                    }","sourceCodeStart":3143,"sourceCodeEnd":3179,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/PersistentTopicsBase.java#L3143-L3179","documentation":"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.","triggerScenarios":"Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/PersistentTopicsBase.java:3161 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Publish messages before calling examine","Verify the subscription name — a wrong subscription can also yield no readable entries"],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}