apache/pulsar · error · ParameterException

Quota type of 'message_age' needs a time limit

Error message

Quota type of 'message_age' needs a time limit

What it means

Backlog-quota option validation in CmdTopicPolicies: the backlog quota type was set to message_age but no time limit (--limit-time) accompanies it, and a message-age quota is meaningless without a duration threshold; the missing time-limit option is the faulty input.

Source

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

            try {
                backlogQuotaType = BacklogQuota.BacklogQuotaType.valueOf(backlogQuotaTypeStr);
            } catch (IllegalArgumentException e) {
                throw new ParameterException(String.format("Invalid backlog quota type '%s'. Valid options are: %s",
                        backlogQuotaTypeStr, Arrays.toString(BacklogQuota.BacklogQuotaType.values())));
            }
            String persistentTopic = validatePersistentTopic(topicName);
            BacklogQuota.Builder builder = BacklogQuota.builder().retentionPolicy(policy);

            if (backlogQuotaType == BacklogQuota.BacklogQuotaType.destination_storage) {
                // set quota by storage size
                if (limit == null) {
                    throw new ParameterException("Quota type of 'destination_storage' needs a size limit");
                }
                builder.limitSize(limit);
            } else {
                // set quota by time
                if (limitTimeInSec == null) {
                    throw new ParameterException("Quota type of 'message_age' needs a time limit");
                }
                builder.limitTime(limitTimeInSec.intValue());
            }
            getTopicPolicies(isGlobal).setBacklogQuota(persistentTopic,
                    builder.build(),
                    backlogQuotaType);
        }
    }

    @Command(description = "Remove a backlog quota policy from a topic")
    private class RemoveBacklogQuota extends CliCommand {

        @Parameters(description = "persistent://tenant/namespace/topic", arity = "1")
        private String topicName;

        @Option(names = {"-t", "--type"}, description = "Backlog quota type to remove")
        private String backlogQuotaType = BacklogQuota.BacklogQuotaType.destination_storage.name();

View on GitHub (pinned to 820761864e)

Solutions

  1. Set --limitTime (time limit) when using --limit for message_age quota

Example fix

// before
pulsar-admin topics set-backlog-quota my-topic --quota-type message_age --limit 10G
// after
pulsar-admin topics set-backlog-quota my-topic --quota-type message_age --limitTime 86400
Defensive patterns

Strategy: validation

Validate before calling

if ("message_age".equals(quotaType) && (limitTimeInSec == null)) {
    throw new IllegalArgumentException("--limitTime (seconds) is required when quota-type is message_age");
}

Prevention

When it happens

Trigger: Running set-backlog-quota with --quota-type message_age but supplying only --limit (a size) and no --limitTime value.

Common situations: Users copying size-based quota examples and switching the type to message_age without swapping --limit for --limitTime; scripts where the limitTime variable defaults to null/empty; confusion between the size --limit flag and the time --limitTime flag.

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/d6a2a953ff35512c. Report an issue: GitHub.