apache/pulsar · warning · IllegalArgumentException

If you set --clear then you should not pass any properties

Error message

If you set --clear then you should not pass any properties

What it means

Mutually-exclusive-options guard in CmdTopics property update: --clear (remove all properties) was combined with explicit -p/--property pairs, which is ambiguous, so the command refuses to run until one of the two is dropped.

Source

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

        @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
        void run() throws Exception {
            String topic = validateTopicName(topicName);
            Map<String, String> result = getTopics().getSubscriptionProperties(topic, subscriptionName);

View on GitHub (pinned to 820761864e)

Solutions

Use either --clear or a property list, not both

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

if (clear && properties != null && !properties.isEmpty()) {
    throw new IllegalArgumentException("--clear cannot be combined with --properties");
}

Try / catch

try {
    admin.topics().updateSubscriptionProperties(topic, sub, props);
} catch (IllegalArgumentException e) {
    log.error("--clear is exclusive; drop it or drop --properties", e);
}

Prevention

Treat --clear as mutually exclusive with --properties
To replace properties, pass the new set without --clear (they overwrite)
Split wipe-then-set into two command invocations if needed

When it happens

Trigger: Running `pulsar-admin topics update-subscription-properties <topic> -s <sub> --clear --properties k=v` — clear is true and the properties map is non-empty.

Common situations: Users wanting to 'reset then set' properties in one call; scripts merging flags where --clear is always appended; misunderstanding that --clear is exclusive, not a precursor.

Related errors

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