apache/pulsar · error · ParameterException

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

Error message

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

What it means

Thrown while setting the subscriptionTypesEnabled topic policy: one of the comma-separated values passed to the subscription-types option cannot be parsed as a SubscriptionType enum constant. Pulsar validates the token with SubscriptionType.valueOf and converts any parse failure into this ParameterException listing all legal values.

Source

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

        @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;

        @Option(names = { "--global", "-g" }, description = "Whether to get this policy globally. "
                + "If set to true, broker returned global topic policies")
        private boolean isGlobal = false;

        @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);
            });
            getTopicPolicies(isGlobal).setSubscriptionTypesEnabled(persistentTopic, types);
        }
    }

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

        @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

View on GitHub (pinned to 820761864e)

Solutions

1. Use exact enum values: Exclusive, Shared, Failover, Key_Shared (as applicable to your version)
2. Match capitalization exactly — valueOf is case-sensitive
3. Remove whitespace or stray characters from the comma-separated list
4. Upgrade the client/broker if the desired subscription type does not exist in this version

Example fix

// before
--subscription-types shared,failover
// after
--subscription-types Shared,Failover

for (String s : subTypes) {
    SubscriptionType.valueOf(s); // throws IllegalArgumentException listing valid constants
}

boolean isKnownSubscriptionType(String s) {
    for (SubscriptionType t : SubscriptionType.values()) {
        if (t.name().equals(s)) return true;
    }
    return false;
}

try {
    admin.topicPolicies().setSubscriptionTypesEnabled(topic, types);
} catch (IllegalArgumentException e) {
    System.err.println("Valid: " + Arrays.toString(SubscriptionType.values()));
}

When it happens

Trigger: Running `pulsar-admin topics set-subscription-types-enabled` with a type string that is not an exact enum constant, e.g. 'shared' instead of 'Shared', 'non-durable' instead of 'NonDurable', or an unknown value.

Common situations: Case mismatch (enum constants are capitalized), using hyphenated or lowercase spellings, listing a type that does not exist in the broker's Pulsar version, or extra whitespace/typos in the comma-separated list.

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

• Invalid retention policy type '%s'. Valid options are: %s
• Need to specify either --enable or --disable
• Invalid interval '%d'.
• Need to provide a persistent topic name
• Need to provide a non-persistent topic name

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