apache/pulsar · warning · ParameterException

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

Error message

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

What it means

When setting a topic backlog quota, the --type value must be a valid BacklogQuota.BacklogQuotaType enum name. An unrecognized string throws IllegalArgumentException, converted to ParameterException listing valid options.

Source

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

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

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

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

View on GitHub (pinned to 820761864e)

Solutions

1. Use an exact valid type name: message_age or target_storage
2. Check the valid options listed in the error message
3. Ensure --type is not confused with --policy (which takes RetentionPolicy values)

Example fix

// before
pulsar-admin topics set-backlog-quota my-topic --type size --limit 100000000
// after
pulsar-admin topics set-backlog-quota my-topic --type target_storage --limit 100000000

Set<String> valid = Set.of("message_age", "target_storage");
if (!valid.contains(typeStr)) {
    throw new IllegalArgumentException("type must be one of " + valid);
}

try {
    BacklogQuota.BacklogQuotaType.valueOf(typeStr);
} catch (IllegalArgumentException e) {
    log.error("Invalid backlog quota type '{}'; valid: {}", typeStr,
        Arrays.toString(BacklogQuota.BacklogQuotaType.values()));
}

When it happens

Trigger: Running `pulsar-admin topics set-backlog-quota <topic> --type <bad-value> ...` where backlogQuotaTypeStr is not exactly message_age or target_storage (the BacklogQuotaType values).

Common situations: Typos or wrong casing; using 'time'/'size' informally instead of the enum names; confusion between policy and type flags; scripts written against different Pulsar versions.

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

• Invalid retention policy type '%s'. Valid options are: %s
• Quota type of 'destination_storage' needs a size limit
• Quota type of 'message_age' needs a time limit
• --offloadedReadPriority parameter must be one of ${allowed}
• Illegal subscription type %s. Possible values: %s.

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