apache/pulsar · error · ParameterException

--bundle and --bundle-type are mutually exclusive

Error message

--bundle and --bundle-type are mutually exclusive

What it means

The splitNamespaceBundle command accepts the bundle either as an explicit range via --bundle or symbolically via --bundle-type, never both. Passing both is ambiguous, so the CLI throws this ParameterException.

Source

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

        @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")
        private String namespaceName;

        @Option(

View on GitHub (pinned to 820761864e)

Solutions

  1. Remove --bundle and rely on --bundle-type, or
  2. Remove --bundle-type and specify the explicit --bundle range

Example fix

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

Strategy: validation

Validate before calling

// shell guard
if [ -n "$BUNDLE" ] && [ -n "$BUNDLE_TYPE" ]; then
  echo "--bundle and --bundle-type are mutually exclusive" >&2; exit 1;
fi

Type guard

// pseudo: require exclusive bundle selectors
int selectors = ((bundle != null && !bundle.isBlank()) ? 1 : 0) + (bundleType != null ? 1 : 0);
if (selectors != 1) throw new IllegalArgumentException("exactly one of --bundle / --bundle-type");

Try / catch

try {
    admin.namespaces().splitNamespaceBundle(ns, bundle, unload, algorithm);
} catch (IllegalArgumentException e) {
    // strip the redundant flag and retry
}

Prevention

When it happens

Trigger: Running split-bundle with both a non-blank --bundle value and a --bundle-type value: StringUtils.isNotBlank(bundle) && bundleType != null.

Common situations: Scripts built up incrementally that kept --bundle and later added --bundle-type; copy-pasted command lines merging two variants of the same command.

Related errors

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