apache/pulsar · warning · ParameterException

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

Error message

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

What it means

When setting a topic backlog quota, the --policy value must be a valid BacklogQuota.RetentionPolicy enum name. An unrecognized string throws IllegalArgumentException, which the CLI converts to ParameterException listing valid options.

Source

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

                        + "[producer_request_hold, producer_exception, consumer_backlog_eviction]", required = true)
        private String policyStr;

        @Option(names = {"-t", "--type"}, description = "Backlog quota type to set. Valid options are: "
                + "destination_storage and message_age. "
                + "destination_storage limits backlog by size (in bytes). "
                + "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();

        @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);
            getTopics().setBacklogQuota(persistentTopic,
                    BacklogQuota.builder().limitSize(limit)
                            .limitTime(limitTimeInSec.intValue())
                            .retentionPolicy(policy)
                            .build(),
                    backlogQuotaType);
        }

View on GitHub (pinned to 820761864e)

Solutions

Use an exact valid policy name: producer_exception, producer_request_hold, or consumer_backlog_eviction
Check the valid options printed in the error message
Note names are case-sensitive — no uppercase or hyphenated variants

Example fix

// before
pulsar-admin topics set-backlog-quota my-topic --policy evict ... 
// after
pulsar-admin topics set-backlog-quota my-topic --policy consumer_backlog_eviction ...

Defensive patterns

Strategy: validation

Validate before calling

Set<String> valid = Set.of("producer_exception", "producer_request_hold", "consumer_backlog_eviction");
if (!valid.contains(policyStr)) {
    throw new IllegalArgumentException("policy must be one of " + valid);
}

Try / catch

try {
    BacklogQuota.RetentionPolicy.valueOf(policyStr);
} catch (IllegalArgumentException e) {
    log.error("Invalid retention policy '{}'; valid: {}", policyStr,
        Arrays.toString(BacklogQuota.RetentionPolicy.values()));
}

Prevention

Use exact lowercase enum names: producer_exception, producer_request_hold, consumer_backlog_eviction
Remember valueOf is case-sensitive
Copy values from the error message's 'Valid options' list

When it happens

Trigger: Running `pulsar-admin topics set-backlog-quota <topic> --policy <bad-value> ...` where policyStr is not exactly one of the RetentionPolicy values (producer_exception, producer_request_hold, consumer_backlog_eviction).

Common situations: Typos or wrong casing (valueOf is case-sensitive); using names from other contexts; older/newer enum names; quoting issues in shell scripts.

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

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