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

When setting a namespace backlog quota, the --retention-policy value is parsed with BacklogQuota.RetentionPolicy.valueOf(). Any string other than the enum constants (producer_exception, producer_request_hold, consumer_backlog_eviction, target_storage, etc. depending on version) fails parsing and the CLI throws this ParameterException listing the valid values.

Source

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

                required = true)
        private String policyStr;

        @Option(names = {"-t", "--type"}, description = "Backlog quota type to set. Valid options are: "
                + "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();

        @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 namespace = validateNamespace(namespaceName);

            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");
                }

View on GitHub (pinned to 820761864e)

Solutions

  1. Use one of the values printed in the error message from Arrays.toString(RetentionPolicy.values())
  2. Fix case/typos — valueOf is case-sensitive (e.g. use producer_exception)
  3. Check the enum values for your exact Pulsar version

Example fix

// before
pulsar-admin namespaces set-backlog-quota my-tenant/my-ns --retention-policy Reject --limit-size 10G
// after
pulsar-admin namespaces set-backlog-quota my-tenant/my-ns --retention-policy producer_exception --limit-size 10G
Defensive patterns

Strategy: validation

Validate before calling

// pre-check in Java before invoking
boolean valid = Arrays.stream(BacklogQuota.RetentionPolicy.values())
        .anyMatch(v -> v.name().equals(policyStr));

Type guard

function isValidRetentionPolicy(s) { return ['producer_exception','producer_request_hold','consumer_backlog_eviction','target_storage'].includes(s); }

Try / catch

try {
    admin.namespaces().setBacklogQuota(ns, quota, type);
} catch (IllegalArgumentException e) {
    // print BacklogQuota.RetentionPolicy.values() and correct the argument
}

Prevention

When it happens

Trigger: Running `pulsar-admin namespaces set-backlog-quota <ns> --retention-policy <bad-string> ...` where policyStr is not an exact RetentionPolicy constant (case-sensitive valueOf).

Common situations: Typos or wrong case (e.g. 'Producer_Exception'); inventing values like 'reject' or 'drop'; copying values from a different Pulsar version where the enum changed.

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