apache/pulsar · error · ParameterException

Quota type of 'destination_storage' needs a size limit

Error message

Quota type of 'destination_storage' needs a size limit

What it means

When the backlog quota type is destination_storage, the quota must carry a byte-size limit; the CLI enforces that --limit is provided. If limit is null the command throws this ParameterException instead of sending an incomplete BacklogQuota to the broker.

Source

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

            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 {
                // set quota by time
                if (limitTimeInSec == null) {
                    throw new ParameterException("Quota type of 'message_age' needs a time limit");
                }
                builder.limitTime(limitTimeInSec.intValue());
            }
            getTopicPolicies(isGlobal).setBacklogQuota(persistentTopic,
                    builder.build(),
                    backlogQuotaType);
        }
    }

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

View on GitHub (pinned to 820761864e)

Solutions

  1. Add a size limit, e.g. --limit 10G, when using --quota-type destination_storage
  2. If you intended a time-based quota, use --quota-type message_age together with --limitTime instead

Example fix

// before
pulsar-admin topics set-backlog-quota my-topic --quota-type destination_storage --limitTime 3600
// after
pulsar-admin topics set-backlog-quota my-topic --quota-type destination_storage --limit 10G
Defensive patterns

Strategy: validation

Validate before calling

if ("destination_storage".equals(quotaType) && (limit == null || limit.isEmpty())) {
    throw new IllegalArgumentException("--limit (size) is required when quota-type is destination_storage");
}

Prevention

When it happens

Trigger: Running set-backlog-quota with --quota-type destination_storage (or the default type when no --quota-type is given, depending on code path) but omitting the --limit flag (e.g. only passing --limitTime).

Common situations: Scripts converted from message_age quotas where --limitTime is set instead of --limit; users assuming a broker default size applies when the flag is omitted; copying an example that uses time-based quotas.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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