apache/pulsar · warning · IllegalArgumentException

If you want to clear the properties you have to use --clear

Error message

If you want to clear the properties you have to use --clear

What it means

The update-subscription-properties command requires that clearing all properties be explicit. If the resulting properties map is empty and --clear was not passed, the command throws IllegalArgumentException, since passing no properties without --clear is ambiguous (a no-op vs. clearing).

Source

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

                "--subscription" }, description = "Subscription to update", required = true)
        private String subscriptionName;

        @Option(names = {"--property", "-p"}, description = "key value pair properties(-p a=b -p c=d)",
                required = false)
        private Map<String, String> properties;

        @Option(names = {"--clear", "-c"}, description = "Remove all properties",
                required = false)
        private boolean clear;

        @Override
        void run() throws Exception {
            String topic = validateTopicName(topicName);
            if (properties == null) {
                properties = Collections.emptyMap();
            }
            if ((properties.isEmpty()) && !clear) {
                throw new IllegalArgumentException("If you want to clear the properties you have to use --clear");
            }
            if (clear && !properties.isEmpty()) {
                throw new IllegalArgumentException("If you set --clear then you should not pass any properties");
            }
            getTopics().updateSubscriptionProperties(topic, subscriptionName, properties);
        }
    }

    @Command(description = "Get the properties of a subscription on a topic")
    private class GetSubscriptionProperties extends CliCommand {
        @Parameters(description = "persistent://tenant/namespace/topic", arity = "1")
        private String topicName;

        @Option(names = { "-s",
                "--subscription" }, description = "Subscription to describe", required = true)
        private String subscriptionName;

        @Override

View on GitHub (pinned to 820761864e)

Solutions

Add --clear when you intend to remove all subscription properties
Or supply at least one key=value via --properties if you meant to set properties
If a no-op was intended, add --clear to satisfy validation or skip running the command

Example fix

// before
pulsar-admin topics update-subscription-properties my-topic -s sub1
// after
pulsar-admin topics update-subscription-properties my-topic -s sub1 --clear

Defensive patterns

Strategy: validation

Validate before calling

if ((properties == null || properties.isEmpty()) && !clear) {
    throw new IllegalArgumentException("Pass --clear to wipe subscription properties");
}

Try / catch

try {
    admin.topics().updateSubscriptionProperties(topic, sub, props);
} catch (IllegalArgumentException e) {
    log.error("Use --clear to remove all subscription properties", e);
}

Prevention

Add --clear whenever you intend to remove all properties
Don't run update-subscription-properties with no arguments expecting a no-op
Explicitly pass the properties you want to keep/set

When it happens

Trigger: Running `pulsar-admin topics update-subscription-properties <topic> -s <sub>` with no --properties and without --clear, so properties.isEmpty() && !clear.

Common situations: Users wanting to wipe all subscription properties but forgetting the --clear flag; scripts passing an empty properties list; copy-pasted commands stripped of the --properties argument.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

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