apache/pulsar · error · ParameterException

Either --compatibility or --disabled must be specified

Error message

Either --compatibility or --disabled must be specified

What it means

Thrown by the legacy 'set-schema-compatibility-strategy' namespace command when the strategy string does not match any of the hardcoded aliases it recognizes (BACKWARD, FORWARD, NONE, etc.). The command only maps a fixed set of legacy names to SchemaAutoUpdateCompatibilityStrategy values and rejects anything else with this generic message. Note NONE maps to AlwaysCompatible, which surprises many users.

Solutions

Use one of the legacy-accepted values: BACKWARD, FORWARD, NONE (meaning always-compatible) — uppercase exactly as documented.
Prefer the newer command based on SchemaCompatibilityStrategy (it accepts all enum values and gives a clearer error), e.g. set-schema-compatibility-strategy with --compatibility FULL_TRANSITIVE where available.
Check the command's help output for the exact accepted set before scripting.

Example fix

// before
pulsar-admin namespaces set-schema-compatibility-strategy public/default --compatibility FULL
// after
pulsar-admin namespaces set-schema-compatibility-strategy public/default --compatibility BACKWARD

Defensive patterns

Strategy: validation

Validate before calling

S="$COMPAT"
if [[ ! "$S" =~ ^(BACKWARD|FORWARD|NONE)$ ]]; then echo "legacy command accepts only BACKWARD, FORWARD, NONE (got: $S)"; exit 1; fi

Prevention

On the legacy command use only BACKWARD, FORWARD, or NONE (NONE = always compatible).
Remember the mapping NONE -> AlwaysCompatible when migrating.
Prefer the modern SchemaCompatibilityStrategy-based command for values like FULL or *_TRANSITIVE.

When it happens

Trigger: Running the legacy set-schema-compatibility-strategy command with a value not in its hardcoded list (e.g. 'always_incompatible', 'FULL', 'UNDEFINED', lowercase 'backward'), or an empty string.

Common situations: Using values valid for the newer set-schema-compatibility-strategy (SchemaCompatibilityStrategy enum: ALWAYS_COMPATIBLE, BACKWARD_TRANSITIVE, FULL, etc.) on the legacy command; case mismatch; reading docs for the modern command and applying them here.

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/3711da03399641b3. Report an issue: GitHub.

Appendix: source

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

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

            SchemaAutoUpdateCompatibilityStrategy strategy = null;
            String strategyStr = strategyParam != null ? strategyParam.toUpperCase() : "";
            if (disabled) {
                strategy = SchemaAutoUpdateCompatibilityStrategy.AutoUpdateDisabled;
            } else if (strategyStr.equals("FULL")) {
                strategy = SchemaAutoUpdateCompatibilityStrategy.Full;
            } else if (strategyStr.equals("BACKWARD")) {
                strategy = SchemaAutoUpdateCompatibilityStrategy.Backward;
            } else if (strategyStr.equals("FORWARD")) {
                strategy = SchemaAutoUpdateCompatibilityStrategy.Forward;
            } else if (strategyStr.equals("NONE")) {
                strategy = SchemaAutoUpdateCompatibilityStrategy.AlwaysCompatible;
            } else {
                throw new ParameterException("Either --compatibility or --disabled must be specified");
            }
            getAdmin().namespaces().setSchemaAutoUpdateCompatibilityStrategy(namespace, strategy);
        }
    }

    @Command(description = "Get the schema compatibility strategy for a namespace")
    private class GetSchemaCompatibilityStrategy 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().getSchemaCompatibilityStrategy(namespace)
                    .toString().toUpperCase());
        }
    }

View on GitHub (pinned to 820761864e)