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

In SetInactiveTopicPolicies, the --delete-mode value is parsed with InactiveTopicDeleteMode.valueOf. If it is not exactly one of the enum constants (delete_when_no_subscriptions or delete_when_subscriptions_caught_up), the IllegalArgumentException is rethrown as this ParameterException. Note the message omits case-sensitivity warning — valueOf is exact-match.

Source

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

                converter = TimeUnitToSecondsConverter.class)
        private Long maxInactiveDurationInSeconds;

        @Option(names = { "--delete-mode", "-m" }, description = "Mode of delete inactive topic, Valid options are: "
                + "[delete_when_no_subscriptions, delete_when_subscriptions_caught_up]", required = true)
        private String inactiveTopicDeleteMode;

        @Override
        void run() throws PulsarAdminException {
            String persistentTopic = validatePersistentTopic(topicName);
            if (enableDeleteWhileInactive == disableDeleteWhileInactive) {
                throw new IllegalArgumentException("Need to specify either enable-delete-while-inactive "
                        + "or disable-delete-while-inactive");
            }
            InactiveTopicDeleteMode deleteMode = null;
            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");
            }
            getTopics().setInactiveTopicPolicies(persistentTopic, new InactiveTopicPolicies(deleteMode,
                    maxInactiveDurationInSeconds.intValue(), enableDeleteWhileInactive));
        }
    }

    @Command(description = "Remove inactive topic policies from a topic", hidden = true)
    private class RemoveInactiveTopicPolicies extends CliCommand {
        @Parameters(description = "persistent://tenant/namespace/topic", arity = "1")
        private String topicName;

        @Override
        void run() throws PulsarAdminException {
            String persistentTopic = validatePersistentTopic(topicName);
            getTopics().removeInactiveTopicPolicies(persistentTopic);
        }
    }

View on GitHub (pinned to 820761864e)

Solutions

Use exactly `--delete-mode delete_when_no_subscriptions` or `--delete-mode delete_when_subscriptions_caught_up`.
Match the snake_case spelling with underscores, not hyphens, and all lowercase.
Check available modes via the enum InactiveTopicDeleteMode or the get-inactive-topic-policies output.

Example fix

// before
bin/pulsar-admin topics set-inactive-topic-policies my-topic --delete-mode delete-when-no-subscriptions --enable-delete-while-inactive
// after
bin/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

// validate delete mode before invoking
case "$DELETE_MODE" in
  delete_when_no_subscriptions|delete_when_subscriptions_caught_up) ;;
  *) echo "invalid --delete-mode: $DELETE_MODE"; exit 1;;
esac

Prevention

Use exact snake_case enum values with underscores, not hyphens.
All lowercase — valueOf matching is case-sensitive.
Keep a constants file for CLI enum values reused across scripts.

When it happens

Trigger: Running `pulsar-admin topics set-inactive-topic-policies <topic> --delete-mode <value>` with misspelled, wrong-cased, or kebab-cased values like `delete-when-no-subscriptions` or `DeleteWhenNoSubscriptions`.

Common situations: Converting the enum constants to kebab-case to match CLI flag style; copying mode names from broker.conf where formatting differs; typos in automation scripts.

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