apache/pulsar · error · ParameterException

Must pass one of the params: --bundle

Error message

Must pass one of the params: --bundle

What it means

The getTopicHashPositions command (topic hash-position lookup on a namespace bundle) needs the specific bundle whose hash positions you want. With a blank --bundle the CLI cannot proceed and throws this ParameterException.

Source

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

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

        @Option(
                names = { "--topic-list",  "-tl" },
                description = "The list of topics(both non-partitioned topic and partitioned topic) to get positions "
                        + "in this bundle, if none topic provided, will get the positions of all topics in this bundle",
                required = false)
        private List<String> topics;

        @Override
        void run() throws PulsarAdminException {
            String namespace = validateNamespace(namespaceName);
            if (StringUtils.isBlank(bundle)) {
                throw new ParameterException("Must pass one of the params: --bundle ");
            }
            print(getAdmin().namespaces().getTopicHashPositions(namespace, bundle, topics));
        }
    }

    @Command(description = "Set message-dispatch-rate for all topics of the namespace")
    private class SetDispatchRate extends CliCommand {
        @Parameters(description = "tenant/namespace", arity = "1")
        private String namespaceName;

        @Option(names = { "--msg-dispatch-rate",
                "-md" }, description = "message-dispatch-rate "
                + "(default -1 will be overwrite if not passed)", required = false)
        private int msgDispatchRate = -1;

        @Option(names = { "--byte-dispatch-rate",
                "-bd" }, description = "byte-dispatch-rate "
                + "(default -1 will be overwrite if not passed)", required = false)

View on GitHub (pinned to 820761864e)

Solutions

  1. Pass --bundle <bundle-range>, e.g. --bundle '0x00000000_0xffffffff'
  2. Obtain valid bundle ranges first via `pulsar-admin namespaces topics`-style bundle listing / get-bundles, then pass one

Example fix

// before
BUNDLE=""  # never populated
pulsar-admin namespaces get-topic-hash-positions my-tenant/my-ns --bundle "$BUNDLE"
// after
BUNDLE=$(pulsar-admin namespaces get-bundles my-tenant/my-ns | head -1)
pulsar-admin namespaces get-topic-hash-positions my-tenant/my-ns --bundle "$BUNDLE" --topics topic-1
Defensive patterns

Strategy: validation

Validate before calling

// shell guard
if [ -z "$BUNDLE" ]; then
  BUNDLE=$(pulsar-admin namespaces get-bundles "$NS" | head -1)
fi
pulsar-admin namespaces get-topic-hash-positions "$NS" --bundle "$BUNDLE"

Type guard

// pseudo
boolean hasBundle = bundle != null && !bundle.isBlank();
if (!hasBundle) throw new IllegalArgumentException("--bundle is required");

Try / catch

try {
    admin.namespaces().getTopicHashPositions(ns, bundle, topics);
} catch (IllegalArgumentException e) {
    // fetch bundle list and retry with a valid bundle
}

Prevention

When it happens

Trigger: Running `pulsar-admin namespaces get-topic-hash-positions <namespace>` (or any invocation of this command's run()) with bundle blank/whitespace: StringUtils.isBlank(bundle) is true.

Common situations: Users omitting --bundle because the optional --topics list was the visible parameter; tooling that interpolates an empty bundle variable when the bundle wasn't discovered first.

Related errors

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