apache/pulsar · warning · ParameterException

Either time (--expireTime) or message position (--position)

Error message

Either time (--expireTime) or message position (--position) has to be provided to expire messages

What it means

The expire-messages command requires at least one expiration criterion: either a relative time (--expireTime) or a message position (--position). If neither is provided, the command cannot determine what to expire and throws ParameterException.

Source

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

        @Option(names = { "-e", "--exclude-reset-position" },
                description = "Exclude the reset position, start consume messages from the next position.")
        private boolean excludeResetPosition = false;

        @Override
        void run() throws PulsarAdminException {
            if (expireTimeInSeconds >= 0 && isNotBlank(messagePosition)) {
                throw new ParameterException(String.format("Can't expire message by time and "
                        + "by message position at the same time."));
            }
            String topic = validateTopicName(topicName);
            if (expireTimeInSeconds >= 0) {
                getTopics().expireMessages(topic, subName, expireTimeInSeconds);
            } else if (isNotBlank(messagePosition)) {
                int partitionIndex = TopicName.get(topic).getPartitionIndex();
                MessageId messageId = validateMessageIdString(messagePosition, partitionIndex);
                getTopics().expireMessages(topic, subName, messageId, excludeResetPosition);
            } else {
                throw new ParameterException(
                        "Either time (--expireTime) or message position (--position) has to be provided"
                                + " to expire messages");
            }
        }
    }

    @Command(description = "Expire messages that older than given expiry time (in seconds) "
            + "for all subscriptions")
    private class ExpireMessagesForAllSubscriptions extends CliCommand {
        @Parameters(description = "persistent://tenant/namespace/topic", arity = "1")
        private String topicName;

        @Option(names = {"-t", "--expireTime"}, description = "Expire messages older than time in seconds "
                + "(or minutes, hours, days, weeks eg: 100m, 3h, 2d, 5w)", required = true,
                converter = TimeUnitToSecondsConverter.class)
        private Long expireTimeInSeconds;

        @Override

View on GitHub (pinned to 820761864e)

Solutions

Add --expireTime <seconds> to expire messages older than that duration
Or add --position <ledgerId:entryId> to expire up to a specific message position
Verify the script/variable supplying --expireTime is not empty or negative

Example fix

// before
pulsar-admin topics expire-messages my-topic -s sub1
// after
pulsar-admin topics expire-messages my-topic -s sub1 --expireTime 3600

Defensive patterns

Strategy: validation

Validate before calling

if ((expireTime == null || expireTime < 0) && (position == null || position.isBlank())) {
    throw new IllegalArgumentException("Provide --expireTime or --position");
}

Try / catch

try {
    admin.topics().expireMessages(topic, sub, expireSeconds);
} catch (org.apache.pulsar.client.admin.PulsarAdminException e) {
    log.error("expire-messages requires --expireTime or --position", e);
}

Prevention

Always supply --expireTime (positive seconds) or --position
Check script variables are non-empty before building the command
Remember neither flag has a default value

When it happens

Trigger: Running `pulsar-admin topics expire-messages <topic> -s <subscription>` with no --expireTime (or --expireTime < 0) and no --position.

Common situations: Forgetting that --expireTime must be a positive number of seconds (omitting it entirely); scripts where variables expand to empty; users expecting expiration to default to 'now'.

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

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