apache/pulsar · error · ParameterException

Must pass one of the params: --bundle / --bundle-type

Error message

Must pass one of the params: --bundle / --bundle-type

What it means

The splitNamespaceBundle CLI command requires you to identify the bundle to split either by explicit bundle range (--bundle, e.g. 0x00000000_0xffffffff) or by bundle type (--bundle-type, e.g. largest/Range). If neither is provided the CLI fails fast with this ParameterException instead of guessing a bundle.

Source

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

                "-u" }, description = "Unload newly split bundles after splitting old bundle", required = false)
        private boolean unload;

        @Option(names = { "--split-algorithm-name", "-san" }, description = "Algorithm name for split "
                + "namespace bundle. Valid options are: [range_equally_divide, topic_count_equally_divide, "
                + "specified_positions_divide, flow_or_qps_equally_divide]. Use broker side config if absent"
                , required = false)
        private String splitAlgorithmName;

        @Option(names = { "--split-boundaries",
                "-sb" }, description = "Specified split boundary for bundle split, will split one bundle "
                + "to multi bundles only works with specified_positions_divide algorithm", required = false)
        private List<Long> splitBoundaries;

        @Override
        void run() throws PulsarAdminException {
            String namespace = validateNamespace(namespaceName);
            if (StringUtils.isBlank(bundle) && bundleType == null) {
                throw new ParameterException("Must pass one of the params: --bundle / --bundle-type");
            }
            if (StringUtils.isNotBlank(bundle) && bundleType != null) {
                throw new ParameterException("--bundle and --bundle-type are mutually exclusive");
            }
            bundle = bundleType != null ? bundleType.toString() : bundle;
            if (splitBoundaries == null || splitBoundaries.size() == 0) {
                getAdmin().namespaces().splitNamespaceBundle(
                        namespace, bundle, unload, splitAlgorithmName);
            } else {
                getAdmin().namespaces().splitNamespaceBundle(
                        namespace, bundle, unload, splitAlgorithmName, splitBoundaries);
            }
        }
    }

    @Command(description = "Get the positions for one or more topic(s) in a namespace bundle")
    private class GetTopicHashPositions extends CliCommand {
        @Parameters(description = "tenant/namespace", arity = "1")

View on GitHub (pinned to 820761864e)

Solutions

  1. Pass --bundle <bundle-range> (e.g. --bundle '0x00000000_0xffffffff'), or
  2. Pass --bundle-type (e.g. --bundle-type largest) to let the CLI pick a bundle
  3. Do not pass both at once (mutually exclusive, see error 872)

Example fix

// before
pulsar-admin namespaces split-bundle my-tenant/my-ns
// after
pulsar-admin namespaces split-bundle my-tenant/my-ns --bundle '0x00000000_0xffffffff'
Defensive patterns

Strategy: validation

Validate before calling

// shell guard
if [ -z "$BUNDLE" ] && [ -z "$BUNDLE_TYPE" ]; then
  echo "Provide --bundle or --bundle-type" >&2; exit 1;
fi

Type guard

// pseudo: ensure exactly one bundle selector is present
boolean hasBundle = bundle != null && !bundle.isBlank();
if (!hasBundle && bundleType == null) throw new IllegalArgumentException("--bundle or --bundle-type required");

Try / catch

try {
    admin.namespaces().splitNamespaceBundle(ns, bundle, unload, algorithm);
} catch (IllegalArgumentException e) {
    // re-run after resolving the bundle via get-bundles
}

Prevention

When it happens

Trigger: Running `pulsar-admin namespaces split-bundle <namespace>` (or calling the command's run()) with both the bundle field blank and bundleType null: StringUtils.isBlank(bundle) && bundleType == null.

Common situations: Operators forgetting that split-bundle needs a target bundle; older scripts written before --bundle-type existed that were also missing --bundle; interactive users assuming the command splits all bundles.

Related errors

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