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.

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)

Solutions

1. Use one of the legacy-accepted values: BACKWARD, FORWARD, NONE (meaning always-compatible) — uppercase exactly as documented.
2. 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.
3. 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

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

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

• Illegal schema compatibility strategy %s. Possible values: %
• 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/3711da03399641b3. Report an issue: GitHub.