apache/pulsar · error · ParameterException

Invalid number of bundles. Number of bundles has to be in th

Error message

Invalid number of bundles. Number of bundles has to be in the range of (0, 2^32].

What it means

Thrown by the set-message-ttl-style namespace command (set-number-of-bundles) when the supplied bundle count is negative or exceeds 2^32. Bundles define the namespace's partitioned range space; the broker schema allows (0, 2^32] and the CLI pre-validates before building Policies.

Source

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

    @Command(description = "Creates a new namespace")
    private class Create extends CliCommand {
        @Parameters(description = "tenant/namespace", arity = "1")
        private String namespaceName;

        @Option(names = { "--clusters", "-c" },
                description = "List of clusters this namespace will be assigned", required = false, split = ",")
        private java.util.List<String> clusters;

        @Option(names = { "--bundles", "-b" }, description = "number of bundles to activate", required = false)
        private int numBundles = 0;

        private static final long MAX_BUNDLES = ((long) 1) << 32;

        @Override
        void run() throws PulsarAdminException {
            String namespace = validateNamespace(namespaceName);
            if (numBundles < 0 || numBundles > MAX_BUNDLES) {
                throw new ParameterException(
                        "Invalid number of bundles. Number of bundles has to be in the range of (0, 2^32].");
            }

            Policies policies = new Policies();
            policies.bundles = numBundles > 0 ? BundlesData.builder()
                    .numBundles(numBundles).build() : null;

            if (clusters != null) {
                policies.replication_clusters = new HashSet<>(clusters);
            }

            getAdmin().namespaces().createNamespace(namespace, policies);
        }
    }

    @Command(description = "Deletes a namespace.")
    private class Delete extends CliCommand {
        @Parameters(description = "tenant/namespace", arity = "1")

View on GitHub (pinned to 820761864e)

Solutions

1. Supply a positive bundle count in (0, 2^32], typically a power of two like 16, 64, or 256
2. Never pass negative or 0 intending 'default'; to clear bundles use the appropriate unset/delete API instead
3. Double-check the script computing numBundles for off-by-one or sign errors
4. Remember numBundles > 0 creates BundlesData; anything else is rejected here

Example fix

// before
pulsar-admin namespaces set-number-of-bundles my-tenant/ns --num-bundles -1
// after
pulsar-admin namespaces set-number-of-bundles my-tenant/ns --num-bundles 64

MAX_BUNDLES=4294967296
if (( NUM_BUNDLES <= 0 || NUM_BUNDLES > MAX_BUNDLES )); then echo "numBundles must be in (0, 2^32]"; exit 1; fi

try { ... } catch (ParameterException e) { /* invalid bundle count: correct value, no retry */ }

When it happens

Trigger: Running `pulsar-admin namespaces set-number-of-bundles` (or equivalent) with --num-bundles given a negative number, a value above 4294967296, or a garbage/overflowed value parsed as an int/long.

Common situations: Passing -1 to mean 'unset'; scripting with arithmetic that produces 0 or negatives; confusing max bundles (2^32) with recommended values (usually powers of 2 up to a few thousand); copy-paste of a large sentinel number.

Related errors

• Need to provide a persistent topic name
• Need to provide a non-persistent topic name
• Invalid message id (must be in format: ledgerId:entryId) val
• unable to parse namespaces parameter list:
• unable to parse primary parameter list:

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