apache/pulsar · error · RestException

Input bundles do not cover the whole hash range. first:

Error message

Input bundles do not cover the whole hash range. first:

What it means

Thrown when setting/updating the bundle boundaries of a namespace (setNamespaceBundleData / updateBundles): NamespaceBundleFactory.validateFullRange requires that the supplied bundle partition points span the entire hash range exactly, ending at the maximum hash. The provided partitions did not cover the full range, so the broker returns HTTP 400 BAD_REQUEST including the first and last partition points for diagnosis.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/NamespacesBase.java:2391

                                "Subscription has active connected consumers");
                    }
                    throw new RestException(cause);
                });
    }

    protected BundlesData validateBundlesData(BundlesData initialBundles) {
        SortedSet<String> partitions = new TreeSet<String>();
        for (String partition : initialBundles.getBoundaries()) {
            Long partBoundary = Long.decode(partition);
            partitions.add(String.format("0x%08x", partBoundary));
        }
        if (partitions.size() != initialBundles.getBoundaries().size()) {
                log.debug("Input bundles included repeated partition points. Ignored.");
                    }
        try {
            NamespaceBundleFactory.validateFullRange(partitions);
        } catch (IllegalArgumentException iae) {
            throw new RestException(Status.BAD_REQUEST, "Input bundles do not cover the whole hash range. first:"
                    + partitions.first() + ", last:" + partitions.last());
        }
        List<String> bundles = new ArrayList<>();
        bundles.addAll(partitions);
        return BundlesData.builder()
                .boundaries(bundles)
                .numBundles(bundles.size() - 1)
                .build();
    }

    private CompletableFuture<Void> validatePoliciesAsync(NamespaceName ns, Policies policies) {
        if (!policies.checkAllowedAndReplicationClusters()) {
            String msg = String.format("[%s] All replication clusters should be included in allowed clusters."
                    + " Repl clusters: %s, allowed clusters: %s",
                    ns.toString(), policies.replication_clusters, policies.allowed_clusters);
            log.info(msg);
            return FutureUtil.failedFuture(new RestException(Status.BAD_REQUEST, msg));
        }

View on GitHub (pinned to 820761864e)

Solutions

1. Ensure the boundaries list starts with '0x00000000' and ends with '0xffffffff' (case-insensitive) and is strictly increasing
2. Validate with validateFullRange-style logic client-side before submitting
3. If you only want N bundles, use the numBundles parameter (getBundles(numBundles)) instead of hand-crafting boundaries
4. Deduplicate and sort the partition list before calling the API

Example fix

// before
List<String> boundaries = List.of("0x00000000", "0x40000000"); // missing end -> 400
admin.namespaces().setNamespaceBundleData("my-tenant/my-ns", boundaries);
// after
List<String> boundaries = List.of("0x00000000", "0x40000000", "0xffffffff");
admin.namespaces().setNamespaceBundleData("my-tenant/my-ns", boundaries);

List<String> b = boundaries.stream().distinct().sorted().collect(Collectors.toList());
if (b.isEmpty() || !b.get(0).equalsIgnoreCase("0x00000000")
        || !b.get(b.size() - 1).equalsIgnoreCase("0xffffffff")) {
    throw new IllegalArgumentException("Boundaries must start at 0x00000000 and end at 0xffffffff");
}

try {
    admin.namespaces().setNamespaceBundleData(ns, boundaries);
} catch (PulsarAdminException e) {
    log.error("Invalid bundle boundaries (must cover full hash range): {}", boundaries);
    throw e;
}

When it happens

Trigger: PUT /namespaces/{ns}/bundles with a boundaries list whose first element is not the minimum hash (0x00000000) or whose last element is not the maximum hash (0xFFFFFFFF); providing a partial list of split points without the endpoints; non-sorted or duplicate boundaries that break full-range coverage after dedup.

Common situations: Hand-computed bundle boundaries missing 0x00000000 or 0xFFFFFFFF endpoints; scripts generating N boundaries but forgetting to include the range start/end; boundaries copied from a namespace with a different bundle count; JSON serialization dropping an endpoint.

Related errors

• Cannot create topic in system topic format!
• Namespace name is not valid
• Tenant name or namespace is not valid
• Topic name is not valid
• Need to provide a persistent topic name

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