apache/pulsar · error · ParameterException

--backlog-scan-max-entries must be greater than 0

Error message

--backlog-scan-max-entries must be greater than 0

What it means

CLI option validation for subscription analysis: the --backlog-scan-max-entries option was given a value of zero or less, which would scan nothing, so AnalyzeSubscriptionBacklog is rejected before starting; the numeric option value is the faulty input.

Source

Thrown at pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdTopics.java:3040

                required = false)
        private boolean plainPrint = false;

        @Override
        void run() throws Exception {
            String persistentTopic = validatePersistentTopic(topicName);
            Optional<MessageId> startPosition = Optional.empty();
            int partitionIndex = TopicName.get(persistentTopic).getPartitionIndex();
            if (isNotBlank(messagePosition)) {
                MessageId messageId = validateMessageIdString(messagePosition, partitionIndex);
                startPosition = Optional.of(messageId);
            }

            AnalyzeSubscriptionBacklogResult backlogResult;
            if (backlogScanMaxEntries == null) {
                backlogResult = getTopics().analyzeSubscriptionBacklog(persistentTopic, subName, startPosition);
            } else {
                if (backlogScanMaxEntries <= 0) {
                    throw new ParameterException("--backlog-scan-max-entries must be greater than 0");
                }
                backlogResult = getTopics().analyzeSubscriptionBacklog(persistentTopic, subName, startPosition,
                        result -> {
                            boolean terminate = result.getEntries() >= backlogScanMaxEntries;
                            if (!quiet && !terminate) {
                                print(result, !plainPrint);
                            }
                            return terminate;
                        });
            }
            print(backlogResult, !plainPrint);
        }
    }

    @Command(description = "Get the schema validation enforced")
    private class GetSchemaValidationEnforced extends CliCommand {
        @Parameters(description = "persistent://tenant/namespace/topic", arity = "1")
        private String topicName;

View on GitHub (pinned to 820761864e)

Solutions

1. Pass a value greater than 0 for --backlog-scan-max-entries
2. Omit the flag to use the default

When it happens

Trigger: Thrown at pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdTopics.java:3040 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/65df29ee7727fcda. Report an issue: GitHub.