apache/pulsar · error · ParameterException

Invalid retention policy type '%s'. Valid options are: %s

Error message

Invalid retention policy type '%s'. Valid options are: %s

What it means

Thrown when setting a backlog quota: the retention policy string cannot be parsed as a BacklogQuota.RetentionPolicy enum constant (or, in the same command, the quota type fails similarly). The valid retention policies are Limit (formerly consumer_backlog_eviction) and RequestTime... precisely the enum constants printed in the message, so the CLI surfaces them for self-correction.

Source

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

                + "destination_storage (default) and message_age. "
                + "destination_storage limits backlog by size. "
                + "message_age limits backlog by time, that is, message timestamp (broker or publish timestamp). "
                + "You can set size or time to control the backlog, or combine them together to control the backlog. ")
        private String backlogQuotaTypeStr = BacklogQuota.BacklogQuotaType.destination_storage.name();

        @Option(names = { "--global", "-g" }, description = "Whether to set this policy globally. "
                + "If set to true, the policy will be replicate to other clusters asynchronously")
        private boolean isGlobal = false;

        @Override
        void run() throws PulsarAdminException {
            BacklogQuota.RetentionPolicy policy;
            BacklogQuota.BacklogQuotaType backlogQuotaType;

            try {
                policy = BacklogQuota.RetentionPolicy.valueOf(policyStr);
            } catch (IllegalArgumentException e) {
                throw new ParameterException(String.format("Invalid retention policy type '%s'. Valid options are: %s",
                        policyStr, Arrays.toString(BacklogQuota.RetentionPolicy.values())));
            }
            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 {

View on GitHub (pinned to 820761864e)

Solutions

1. Use exact enum values, e.g. consumer_backlog_eviction or request_time_out (see the message's list for your version)
2. Match capitalization and underscores exactly
3. Check you passed the policy string to --policy and the quota type to --type, not swapped
4. Consult Arrays.toString(RetentionPolicy.values()) output in the error for the authoritative set

Example fix

// before
--policy limit
// after
--policy consumer_backlog_eviction

BacklogQuota.RetentionPolicy.valueOf(policyStr); // throws with valid options on failure
BacklogQuota.BacklogQuotaType.valueOf(quotaTypeStr);

boolean isValidRetentionPolicy(String s) {
    for (BacklogQuota.RetentionPolicy p : BacklogQuota.RetentionPolicy.values()) {
        if (p.name().equals(s)) return true;
    }
    return false;
}

try {
    admin.topicPolicies().setBacklogQuota(topic, quota, policyType);
} catch (IllegalArgumentException e) {
    System.err.println("Valid policies: " + Arrays.toString(BacklogQuota.RetentionPolicy.values()));
}

When it happens

Trigger: Running `pulsar-admin namespaces set-backlog-quota` (topic-policies equivalent) with --policy set to something other than an exact RetentionPolicy constant, e.g. 'evict' or lowercase 'limit'.

Common situations: Older documentation using legacy policy names, lowercase enum spellings, typos, or confusing RetentionPolicy with BacklogQuotaType in the flag order.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Illegal subscription type %s. Possible values: %s.
• Need to specify either --enable or --disable
• Invalid interval '%d'.
• Need to provide a persistent topic name
• Need to provide a non-persistent topic name

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