apache/pulsar · error · ParameterException

Illegal subscription type %s. Possible values: %s.

Error message

Illegal subscription type %s. Possible values: %s.

What it means

The set-subscription-types-enabled command parses each comma-separated --type value with SubscriptionType.valueOf. Any token that is not an exact enum constant name (Exclusive, Shared, Failover, Key_Shared) throws this ParameterException listing all possible values.

Source

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

    @Command(description = "Set subscription types enabled for a topic", hidden = true)
    private class SetSubscriptionTypesEnabled extends CliCommand {
        @Parameters(description = "persistent://tenant/namespace/topic", arity = "1")
        private String topicName;

        @Option(names = {"--types", "-t"}, description = "Subscription types enabled list (comma separated values)."
                + " Possible values: (Exclusive, Shared, Failover, Key_Shared).", required = true, split = ",")
        private List<String> subTypes;

        @Override
        void run() throws PulsarAdminException {
            String persistentTopic = validatePersistentTopic(topicName);
            Set<SubscriptionType> types = new HashSet<>();
            subTypes.forEach(s -> {
                SubscriptionType subType;
                try {
                    subType = SubscriptionType.valueOf(s);
                } catch (IllegalArgumentException exception) {
                    throw new ParameterException(String.format("Illegal subscription type %s. Possible values: %s.", s,
                            Arrays.toString(SubscriptionType.values())));
                }
                types.add(subType);
            });
            getTopics().setSubscriptionTypesEnabled(persistentTopic, types);
        }
    }

    @Command(description = "Get subscription types enabled for a topic", hidden = true)
    private class GetSubscriptionTypesEnabled extends CliCommand {
        @Parameters(description = "persistent://tenant/namespace/topic", arity = "1")
        private String topicName;

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

View on GitHub (pinned to 820761864e)

Solutions

  1. Use exact enum names: Exclusive, Shared, Failover, or Key_Shared.
  2. Pass multiple types comma-separated without spaces, e.g. --type Shared,Key_Shared.
  3. Check the Possible values list in the error message for your Pulsar version.

Example fix

// before
bin/pulsar-admin topics set-subscription-types-enabled my-topic --type shared,key-shared
// after
bin/pulsar-admin topics set-subscription-types-enabled my-topic --type Shared,Key_Shared
Defensive patterns

Strategy: validation

Validate before calling

// validate each comma-separated subscription type
VALID="Exclusive,Shared,Failover,Key_Shared"
IFS=',' read -ra PARTS <<< "$TYPES"
for t in "${PARTS[@]}"; do
  if ! echo ",$VALID," | grep -q ",$t,"; then
    echo "illegal subscription type: $t (possible: $VALID)"; exit 1;
  fi
done

Prevention

When it happens

Trigger: Running `pulsar-admin topics set-subscription-types-enabled <topic> --type <value>` with a misspelled or wrong-cased type such as `shared`, `key-shared`, or `KeyShared`.

Common situations: Translating documentation naming (`Key_Shared`) into kebab-case; enabling multiple types but misformatting the list; case sensitivity — valueOf is case-sensitive.

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