apache/pulsar · error · ParameterException

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

Error message

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

What it means

Thrown when a --sub-type value passed to the set-subscription-types-enabled command cannot be resolved to a pulsar.common.util.SubscriptionType enum constant via valueOf. The message lists all legal values so the caller can correct the input.

Source

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

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

        @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 namespace = validateNamespace(namespaceName);
            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);
            });
            getAdmin().namespaces().setSubscriptionTypesEnabled(namespace, types);
        }
    }

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

        @Override
        void run() throws PulsarAdminException {
            String namespace = validateNamespace(namespaceName);
            print(getAdmin().namespaces().getSubscriptionTypesEnabled(namespace));
        }

View on GitHub (pinned to 820761864e)

Solutions

  1. Use exact enum names: SubscriptionType.values() shows them, e.g. --sub-type Shared --sub-type Failover --sub-type Key_Shared
  2. Match case exactly (valueOf is case-sensitive)
  3. Repeat the --sub-type flag once per type instead of comma-joining
  4. Check SubscriptionType constants for your Pulsar version (Key_Shared requires a recent version)

Example fix

// before
pulsar-admin namespaces set-subscription-types-enabled t/ns --sub-type shared
// after
pulsar-admin namespaces set-subscription-types-enabled t/ns --sub-type Shared --sub-type Failover
Defensive patterns

Strategy: validation

Validate before calling

VALID='Exclusive Shared Failover Key_Shared'
for t in $SUB_TYPES; do [[ " $VALID " == *" $t "* ]] || { echo "illegal subscription type: $t"; exit 1; }; done

Type guard

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

Try / catch

try { ... } catch (ParameterException e) { /* bad enum name: use exact SubscriptionType names */ }

Prevention

When it happens

Trigger: Running `pulsar-admin namespaces set-subscription-types-enabled <ns> --sub-type` with an invalid name such as 'Exclusive', 'shared' in wrong case, or a typo like 'Failovered'. Only enum constants of SubscriptionType (e.g. Exclusive, Shared, Failover, Key_Shared) are accepted.

Common situations: Lowercasing enum names in scripts ('shared' instead of 'Shared'); using documentation terms like 'non-durable' which are not SubscriptionType constants; version drift where a type like Key_Shared doesn't exist in older clients; multiple values separated incorrectly.

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