apache/pulsar · error · ParameterException

Invalid backlog quota type '%s'. Valid options are: %s

Error message

Invalid backlog quota type '%s'. Valid options are: %s

What it means

The --backlog-quota-type argument of set-backlog-quota is parsed with BacklogQuota.BacklogQuotaType.valueOf(). Only the enum constants (destination_storage, message_age) are accepted; anything else throws this ParameterException listing valid options.

Source

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

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

View on GitHub (pinned to 820761864e)

Solutions

  1. Use 'destination_storage' for size-based quotas or 'message_age' for time-based quotas
  2. Match exact case and underscores as printed in the error
  3. Verify the enum on your Pulsar version if upgrading

Example fix

// before
pulsar-admin namespaces set-backlog-quota my-tenant/my-ns --backlog-quota-type destination-storage --limit-size 5G
// after
pulsar-admin namespaces set-backlog-quota my-tenant/my-ns --backlog-quota-type destination_storage --limit-size 5G
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

function isValidBacklogQuotaType(s) { return ['destination_storage','message_age'].includes(s); }

Try / catch

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

Prevention

When it happens

Trigger: Running `pulsar-admin namespaces set-backlog-quota <ns> --backlog-quota-type <bad-string> ...` where backlogQuotaTypeStr doesn't exactly match a BacklogQuotaType constant.

Common situations: Typing 'destination-storage' or 'storage' instead of 'destination_storage'; wrong case ('Message_Age'); scripts ported from configs that use hyphenated or camelCase names.

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