apache/pulsar · error · ParameterException

delete mode can only be set to delete_when_no_subscriptions

Error message

delete mode can only be set to delete_when_no_subscriptions or delete_when_subscriptions_caught_up

What it means

The --delete-mode value for set-inactive-topic-policies is parsed with InactiveTopicDeleteMode.valueOf(); any string that is not an exact enum constant throws this ParameterException naming the two legal values. The broker is never contacted.

Source

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

                + "[delete_when_no_subscriptions, delete_when_subscriptions_caught_up]", required = true)
        private String inactiveTopicDeleteMode;

        @Option(names = { "--global", "-g" }, description = "Whether to set this policy globally. "
                + "If set to true, the policy will be replicate to other clusters asynchronously")
        private boolean isGlobal = false;

        @Override
        void run() throws PulsarAdminException {
            String persistentTopic = validatePersistentTopic(topicName);
            if (enableDeleteWhileInactive == disableDeleteWhileInactive) {
                throw new ParameterException("Need to specify either enable-delete-while-inactive or "
                        + "disable-delete-while-inactive");
            }
            InactiveTopicDeleteMode deleteMode;
            try {
                deleteMode = InactiveTopicDeleteMode.valueOf(inactiveTopicDeleteMode);
            } catch (IllegalArgumentException e) {
                throw new ParameterException("delete mode can only be set to delete_when_no_subscriptions or "
                        + "delete_when_subscriptions_caught_up");
            }
            getTopicPolicies(isGlobal).setInactiveTopicPolicies(persistentTopic, new InactiveTopicPolicies(deleteMode,
                    maxInactiveDurationInSeconds.intValue(), enableDeleteWhileInactive));
        }
    }

    @Command(description = "Remove inactive topic policies from a topic")
    private class RemoveInactiveTopicPolicies extends CliCommand {
        @Parameters(description = "persistent://tenant/namespace/topic", arity = "1")
        private String topicName;
        @Option(names = { "--global", "-g" }, description = "Whether to remove this policy globally. "
                + "If set to true, the removing operation will be replicate to other clusters asynchronously")
        private boolean isGlobal = false;
        @Override
        void run() throws PulsarAdminException {
            String persistentTopic = validatePersistentTopic(topicName);
            getTopicPolicies(isGlobal).removeInactiveTopicPolicies(persistentTopic);

View on GitHub (pinned to 820761864e)

Solutions

Use exactly delete_when_no_subscriptions or delete_when_subscriptions_caught_up for --delete-mode
Check the enum org.apache.pulsar.common.policies.data.InactiveTopicDeleteMode for the authoritative names

Example fix

// before
pulsar-admin topics set-inactive-topic-policies my-topic --delete-mode delete_when_no_subs --enable-delete-while-inactive
// after
pulsar-admin topics set-inactive-topic-policies my-topic --delete-mode delete_when_no_subscriptions --enable-delete-while-inactive

Defensive patterns

Strategy: validation

Validate before calling

final Set<String> VALID = Set.of("delete_when_no_subscriptions", "delete_when_subscriptions_caught_up");
if (!VALID.contains(deleteMode)) throw new IllegalArgumentException("delete-mode must be one of " + VALID);

Type guard

static boolean isValidInactiveDeleteMode(String s) {
    return Arrays.stream(InactiveTopicDeleteMode.values()).anyMatch(m -> m.name().equals(s));
}

Prevention

Copy enum names exactly; no abbreviations or hyphens
Check your Pulsar version's InactiveTopicDeleteMode enum
Use shell completion where available

When it happens

Trigger: Running set-inactive-topic-policies with --delete-mode values like 'delete_when_no_subs', 'none', 'all', wrong casing, or hyphenated variants of the enum names.

Common situations: Typos or abbreviations in scripts; confusion with retention/inactive values from other messaging systems; documentation from before the 'delete_when_subscriptions_caught_up' mode existed; YAML config strings copied verbatim into CLI flags.

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