apache/pulsar · error · ParameterException

[--bookkeeper-ensemble], [--bookkeeper-write-quorum] and [--

Error message

[--bookkeeper-ensemble], [--bookkeeper-write-quorum] and [--bookkeeper-ack-quorum] must greater than 0.

What it means

The set-persistence command validates that bookkeeper ensemble, write quorum, and ack quorum are all positive before building PersistencePolicies. A value <= 0 for any of --bookkeeper-ensemble, --bookkeeper-write-quorum, or --bookkeeper-ack-quorum would create an invalid replication configuration, so the CLI throws this ParameterException.

Source

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

                description = "Number of acks (guaranteed copies) to wait for each entry")
        private int bookkeeperAckQuorum = 2;

        @Option(names = { "-r",
                "--ml-mark-delete-max-rate" },
                description = "Throttling rate of mark-delete operation "
                        + "(0 means no throttle, -1 means unset which will use the default configuration from broker)")
        private double managedLedgerMaxMarkDeleteRate = -1;

        @Option(names = { "-c",
                "--ml-storage-class" },
                description = "Managed ledger storage class name")
        private String managedLedgerStorageClassName;

        @Override
        void run() throws PulsarAdminException {
            String namespace = validateNamespace(namespaceName);
            if (bookkeeperEnsemble <= 0 || bookkeeperWriteQuorum <= 0 || bookkeeperAckQuorum <= 0) {
                throw new ParameterException("[--bookkeeper-ensemble], [--bookkeeper-write-quorum] "
                        + "and [--bookkeeper-ack-quorum] must greater than 0.");
            }
            getAdmin().namespaces().setPersistence(namespace, new PersistencePolicies(bookkeeperEnsemble,
                    bookkeeperWriteQuorum, bookkeeperAckQuorum, managedLedgerMaxMarkDeleteRate,
                    managedLedgerStorageClassName));
        }
    }

    @Command(description = "Clear backlog for a namespace")
    private class ClearBacklog extends CliCommand {
        @Parameters(description = "tenant/namespace", arity = "1")
        private String namespaceName;

        @Option(names = { "--sub", "-s" }, description = "subscription name")
        private String subscription;

        @Option(names = { "--bundle", "-b" }, description = "{start-boundary}_{end-boundary}")
        private String bundle;

View on GitHub (pinned to 820761864e)

Solutions

  1. Set all three flags to positive integers (e.g. --bookkeeper-ensemble 3 --bookkeeper-write-quorum 3 --bookkeeper-ack-quorum 2)
  2. Ensure write-quorum <= ensemble and ack-quorum <= write-quorum for a valid policy
  3. Fix the script/template so unset variables don't default to 0

Example fix

// before
ENSEMBLE=0  # unset variable defaulted to 0
pulsar-admin namespaces set-persistence my-tenant/my-ns -e $ENSEMBLE -w 3 -a 2
// after
ENSEMBLE=3
pulsar-admin namespaces set-persistence my-tenant/my-ns -e $ENSEMBLE -w 3 -a 2
Defensive patterns

Strategy: validation

Validate before calling

// shell guard
if [ "$ENSEMBLE" -le 0 ] || [ "$WRITE_Q" -le 0 ] || [ "$ACK_Q" -le 0 ]; then
  echo "ensemble/write-quorum/ack-quorum must be > 0" >&2; exit 1;
fi

Type guard

// pseudo: validate positive policy numbers
boolean valid = ensemble > 0 && writeQuorum > 0 && ackQuorum > 0
             && writeQuorum <= ensemble && ackQuorum <= writeQuorum;

Try / catch

try {
    admin.namespaces().setPersistence(ns, policies);
} catch (IllegalArgumentException e) {
    // sanitize defaults and retry with valid positive values
}

Prevention

When it happens

Trigger: Running `pulsar-admin namespaces set-persistence <ns> --bookkeeper-ensemble N --bookkeeper-write-quorum N --bookkeeper-ack-quorum N ...` where any of the three values is 0 or negative.

Common situations: Variables defaulting to 0 in shell scripts when unset (e.g. ${E:-0}); misunderstanding quorum semantics and setting write/ack quorum to 0 to 'disable'; templating bugs that leave a flag at its zero default.

Related errors

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