apache/pulsar · error · PulsarAdminException

Either Timestamp (--time) or Position (--position) has to be

Error message

Either Timestamp (--time) or Position (--position) has to be provided to reset cursor

What it means

`pulsar-admin topics reset-cursor` needs a reset target: either --position (a message id) or --time (a relative offset in ms). If neither option was supplied, the command throws a PulsarAdminException instead of guessing a default reset point.

Source

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

                converter = TimeUnitToMillisConverter.class)
        private Long resetTimeInMillis = null;

        @Option(names = { "--messageId",
                "-m" }, description = "messageId to reset back to (ledgerId:entryId)", required = false)
        private String resetMessageIdStr;

        @Override
        void run() throws PulsarAdminException {
            String persistentTopic = validatePersistentTopic(topicName);
            if (isNotBlank(resetMessageIdStr)) {
                MessageId messageId = validateMessageIdString(resetMessageIdStr);
                getPersistentTopics().resetCursor(persistentTopic, subName, messageId);
            } else if (Objects.nonNull(resetTimeInMillis)) {
                // now - go back time
                long timestamp = System.currentTimeMillis() - resetTimeInMillis;
                getPersistentTopics().resetCursor(persistentTopic, subName, timestamp);
            } else {
                throw new PulsarAdminException(
                        "Either Timestamp (--time) or Position (--position) has to be provided to reset cursor");
            }
        }
    }

    @Command(description = "Terminate a topic and don't allow any more messages to be published")
    private class Terminate extends CliCommand {
        @Parameters(description = "persistent://tenant/namespace/topic", arity = "1")
        private String topicName;

        @Override
        void run() throws PulsarAdminException {
            String persistentTopic = validatePersistentTopic(topicName);

            try {
                MessageId lastMessageId = getPersistentTopics().terminateTopicAsync(persistentTopic).get();
                System.out.println("Topic successfully terminated at " + lastMessageId);
            } catch (InterruptedException | ExecutionException e) {

View on GitHub (pinned to 820761864e)

Solutions

1. Pass --time with a duration in milliseconds/seconds/unit to reset to now-minus-duration, e.g. --time 1h
2. Or pass --position with a message id (e.g. ledgerId:entryId or earliest/latest where supported)
3. Fix script variables so one of the two flags is actually populated

Example fix

// before
pulsar-admin topics reset-cursor persistent://t/n/topic -s my-sub
// after
pulsar-admin topics reset-cursor persistent://t/n/topic -s my-sub --time 1h

if (resetTime == null && resetPosition == null) {
    throw new IllegalArgumentException("Provide either --time or --position to reset a cursor");
}

try {
    persistentTopics.resetCursor(topic, subName, timestampOrMessageId);
} catch (org.apache.pulsar.client.admin.PulsarAdminException e) {
    // prompt for missing --time/--position
}

When it happens

Trigger: Running the reset-cursor command with only the topic and subscription name, leaving both --position and --time unset.

Common situations: Interactive run where the user assumes default behavior of resetting to earliest/latest; automation scripts where a variable holding --time or --position was empty; confusing reset-cursor with the separate `expire-messages` command.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• ${paramName} cannot be bigger than <${maxValue}>!
• ${paramName} cannot be less than or equal to <0>!
• The value of ${paramName} can't be empty
• ${name} cannot be less than <${min}>!
• byte string cannot be empty

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/bcf17c999cd9defb. Report an issue: GitHub.