apache/pulsar · error · ParameterException

Illegal schema compatibility strategy %s. Possible values: %

Error message

Illegal schema compatibility strategy %s. Possible values: %s

What it means

Thrown by the modern schema compatibility command when the --compatibility value cannot be parsed as a SchemaCompatibilityStrategy enum constant. The code uppercases the input, calls SchemaCompatibilityStrategy.valueOf, and converts the IllegalArgumentException into a ParameterException listing all valid enum values. This is strict enum validation performed client-side before the admin API call.

Source

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

        @Option(names = { "--compatibility", "-c" },
                description = "Compatibility level required for new schemas created via a Producer. "
                        + "Possible values (FULL, BACKWARD, FORWARD, "
                        + "UNDEFINED, BACKWARD_TRANSITIVE, "
                        + "FORWARD_TRANSITIVE, FULL_TRANSITIVE, "
                        + "ALWAYS_INCOMPATIBLE,"
                        + "ALWAYS_COMPATIBLE).")
        private String strategyParam = null;

        @Override
        void run() throws PulsarAdminException {
            String namespace = validateNamespace(namespaceName);

            String strategyStr = strategyParam != null ? strategyParam.toUpperCase() : "";
            SchemaCompatibilityStrategy strategy;
            try {
                strategy = SchemaCompatibilityStrategy.valueOf(strategyStr);
            } catch (IllegalArgumentException exception) {
                throw new ParameterException(String.format("Illegal schema compatibility strategy %s. "
                        + "Possible values: %s", strategyStr, Arrays.toString(SchemaCompatibilityStrategy.values())));
            }
            getAdmin().namespaces().setSchemaCompatibilityStrategy(namespace, strategy);
        }
    }

    @Command(description = "Get the namespace whether allow auto update schema")
    private class GetIsAllowAutoUpdateSchema extends CliCommand {
        @Parameters(description = "tenant/namespace", arity = "1")
        private String namespaceName;

        @Override
        void run() throws PulsarAdminException {
            String namespace = validateNamespace(namespaceName);

            System.out.println(getAdmin().namespaces().getIsAllowAutoUpdateSchema(namespace));
        }
    }

View on GitHub (pinned to 820761864e)

Solutions

1. Use an exact SchemaCompatibilityStrategy value, e.g. ALWAYS_COMPATIBLE, BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, NONE (uppercase).
2. Copy the possible-values list from the error message or the command --help output.
3. Trim whitespace and strip hyphens from scripted values before passing the flag.

Example fix

// before
pulsar-admin namespaces set-schema-compatibility-strategy public/default --compatibility backward-transitive
// after
pulsar-admin namespaces set-schema-compatibility-strategy public/default --compatibility BACKWARD_TRANSITIVE

S=$(echo "${COMPAT:-}" | tr 'a-z' 'A-Z' | tr -d '-')
VALID="ALWAYS_COMPATIBLE BACKWARD BACKWARD_TRANSITIVE FORWARD FORWARD_TRANSITIVE FULL FULL_TRANSITIVE NONE"
[[ " $VALID " == *" $S "* ]] || { echo "invalid strategy: $S"; exit 1; }

When it happens

Trigger: Passing an invalid value to the schema compatibility flag (e.g. 'backward-compat', 'BACKWARDTRANSITIVE', 'none') or leaving it empty so strategyStr is ''.

Common situations: Hyphenated or shorthand names not in the enum; missing an underscore (BACKWARDTRANSITIVE vs BACKWARD_TRANSITIVE); using legacy values like ALWAYS_COMPATIBLE spelled differently across Pulsar versions (ALWAYS_COMPATIBLE vs AlwaysCompatible legacy name).

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

• Either --compatibility or --disabled must be specified
• delete mode can only be set to delete_when_no_subscriptions
• Can not enable for all producers but denies for replicators
• 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/6f9348de7150d9d3. Report an issue: GitHub.