apache/pulsar · error · ParameterException

--destinationBroker cannot be set when --bundle is not speci

Error message

--destinationBroker cannot be set when --bundle is not specified.

What it means

The pulsar-admin 'unload namespace' command throws this ParameterException when --destinationBroker is supplied without --bundle. Unloading a whole namespace has no single destination broker (it covers all bundles), so a target broker only makes sense when unloading one specific bundle. The CLI rejects the contradictory combination before calling the admin API.

Source

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

        @Parameters(description = "tenant/namespace", arity = "1")
        private String namespaceName;

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

        @Option(names = { "--destinationBroker", "-d" },
                description = "Target brokerWebServiceAddress to which the bundle has to be allocated to. "
                        + "--destinationBroker cannot be set when --bundle is not specified.")
        private String destinationBroker;

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


            if (bundle == null) {
                if (StringUtils.isNotBlank(destinationBroker)) {
                    throw new ParameterException("--destinationBroker cannot be set when --bundle is not specified.");
                }
                getAdmin().namespaces().unload(namespace);
            } else {
                getAdmin().namespaces().unloadNamespaceBundle(namespace, bundle, destinationBroker);
            }
        }
    }

    @Command(description = "Split a namespace-bundle from the current serving broker")
    private class SplitBundle extends CliCommand {
        @Parameters(description = "tenant/namespace", arity = "1")
        private String namespaceName;

        @Option(names = { "--bundle",
                "-b" }, description = "{start-boundary}_{end-boundary} "
                        + "(mutually exclusive with --bundle-type)", required = false)
        private String bundle;

View on GitHub (pinned to 820761864e)

Solutions

  1. Add a --bundle <bundle-range> argument to the command, or
  2. Remove the --destinationBroker flag when unloading the entire namespace (use plain `unload <namespace>`), or
  3. If the goal is to move a specific bundle, invoke `unload --bundle <bundle> --destinationBroker <broker>`

Example fix

// before
pulsar-admin namespaces unload my-tenant/my-ns --destinationBroker broker-3:6650
// after
pulsar-admin namespaces unload my-tenant/my-ns --bundle '0x00000000_0xffffffff' --destinationBroker broker-3:6650
Defensive patterns

Strategy: validation

Validate before calling

// shell guard before invoking the CLI
if [ -n "$DEST_BROKER" ] && [ -z "$BUNDLE" ]; then
  echo "--destinationBroker requires --bundle" >&2; exit 1;
fi
pulsar-admin namespaces unload "$NS" ${BUNDLE:+--bundle "$BUNDLE"} ${DEST_BROKER:+--destinationBroker "$DEST_BROKER"}

Type guard

// pseudo: reject the invalid combination before dispatch
boolean invalid = (destinationBroker != null && !destinationBroker.isBlank()) && (bundle == null);
if (invalid) throw new IllegalArgumentException("--destinationBroker requires --bundle");

Try / catch

try {
    admin.namespaces().unload(ns);
} catch (IllegalArgumentException e) {
    // log the flag misuse and correct the command arguments
}

Prevention

When it happens

Trigger: Running `pulsar-admin namespaces unload <namespace> --destinationBroker <broker>` (or the equivalent CliCommand invocation with destinationBroker set and bundle == null). The run() method checks StringUtils.isNotBlank(destinationBroker) while bundle is null.

Common situations: Operators scripting namespace unload who copy the --destinationBroker flag from a bundle-unload example; automation templates that always append --destinationBroker regardless of whether a bundle was selected.

Related errors

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