apache/pulsar · error · ParameterException

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

Q: What causes "[--bookkeeper-ensemble], [--bookkeeper-write-quorum] and [--bookkeeper-ack-quorum] must greater than 0." in apache/pulsar?

Set all three flags to positive integers, e.g. `--bookkeeper-ensemble 3 --bookkeeper-write-quorum 3 --bookkeeper-ack-quorum 2`.

Error message

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

What it means

The SetPersistence command requires the BookKeeper ensemble, write quorum, and ack quorum values to each be strictly positive before calling setPersistence. If any of --bookkeeper-ensemble, --bookkeeper-write-quorum, or --bookkeeper-ack-quorum is <= 0, it throws a ParameterException naming all three flags.

Source

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

        @Option(names = { "-a",
                "--bookkeeper-ack-quorum" }, 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 configuration from namespace or 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 persistentTopic = validatePersistentTopic(topicName);
            if (bookkeeperEnsemble <= 0 || bookkeeperWriteQuorum <= 0 || bookkeeperAckQuorum <= 0) {
                throw new ParameterException("[--bookkeeper-ensemble], [--bookkeeper-write-quorum] "
                        + "and [--bookkeeper-ack-quorum] must greater than 0.");
            }
            getTopics().setPersistence(persistentTopic, new PersistencePolicies(bookkeeperEnsemble,
                    bookkeeperWriteQuorum, bookkeeperAckQuorum, managedLedgerMaxMarkDeleteRate,
                    managedLedgerStorageClassName));
        }
    }

    @Command(description = "Remove the persistence policy for a topic", hidden = true)
    private class RemovePersistence extends CliCommand {
        @Parameters(description = "persistent://tenant/namespace/topic", arity = "1")
        private String topicName;

        @Override
        void run() throws PulsarAdminException {
            String persistentTopic = validatePersistentTopic(topicName);
            getTopics().removePersistence(persistentTopic);
        }

View on GitHub (pinned to 820761864e)

Solutions

Set all three flags to positive integers, e.g. `--bookkeeper-ensemble 3 --bookkeeper-write-quorum 3 --bookkeeper-ack-quorum 2`.
Ensure write quorum <= ensemble and ack quorum <= write quorum.
To revert to namespace defaults, use the remove-persistence command instead of zero values.

Example fix

// before
bin/pulsar-admin topics set-persistence my-topic --bookkeeper-ensemble 0 --bookkeeper-write-quorum 0 --bookkeeper-ack-quorum 0
// after
bin/pulsar-admin topics set-persistence my-topic --bookkeeper-ensemble 3 --bookkeeper-write-quorum 3 --bookkeeper-ack-quorum 2

Defensive patterns

Strategy: validation

Validate before calling

// validate quorum relationships before invoking
if [ "$E" -le 0 ] || [ "$WQ" -le 0 ] || [ "$AQ" -le 0 ]; then
  echo "ensemble/write-quorum/ack-quorum must be > 0"; exit 1;
fi
if [ "$WQ" -gt "$E" ] || [ "$AQ" -gt "$WQ" ]; then
  echo "must satisfy ackQuorum <= writeQuorum <= ensemble"; exit 1;
fi

Prevention

Ensemble >= write quorum >= ack quorum >= 1 is the valid invariant.
Use remove-persistence to fall back to defaults instead of zeros.
Guard script variables against empty values defaulting to 0.

When it happens

Trigger: Running `pulsar-admin topics set-persistence <topic>` with any of the three quorum flags set to 0 or a negative number.

Common situations: Zero-initialized variables in scripts; confusing 0 with 'use broker default' (it is not accepted here); setting write quorum greater than ensemble so values are later rejected server-side.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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