apache/pulsar · error · RestException

Bookie 'group' parameters is missing

Error message

Bookie 'group' parameters is missing

What it means

Thrown by the Bookies admin resource when updating a bookie's rack/group placement info (updateBookieRackInfo). The 'group' query parameter is mandatory — the bookie's placement group is part of the rack-aware policy data stored in the metadata service. A null group cannot be persisted, so the request is rejected up front with HTTP 412 PRECONDITION_FAILED.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/Bookies.java:185

    @POST
    @Path("/racks-info/{bookie}")
    @Operation(summary = "Updates the rack placement information for a specific bookie in the cluster (note."
            + " bookie address format:`address:port`)")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "204", description = "Operation successful"),
            @ApiResponse(responseCode = "403", description = "Don't have admin permission")}
    )
    public void updateBookieRackInfo(@Suspended final AsyncResponse asyncResponse,
                                     @Parameter(description = "The bookie address", required = true)
                                     @PathParam("bookie") String bookieAddress,
                                     @Parameter(description = "The group", required = true)
                                     @QueryParam("group") String group,
                                     @RequestBody(description = "The bookie info", required = true)
                                     BookieInfo bookieInfo) throws Exception {
        validateSuperUserAccess();

        if (group == null) {
            throw new RestException(Status.PRECONDITION_FAILED, "Bookie 'group' parameters is missing");
        }

        // validate rack name
        int separatorCnt = StringUtils.countMatches(
            StringUtils.strip(bookieInfo.getRack(), PATH_SEPARATOR), PATH_SEPARATOR);
        boolean isRackEnabled = pulsar().getConfiguration().isBookkeeperClientRackawarePolicyEnabled();
        boolean isRegionEnabled = pulsar().getConfiguration().isBookkeeperClientRegionawarePolicyEnabled();
        if (isRackEnabled && ((isRegionEnabled && separatorCnt != 1) || (!isRegionEnabled && separatorCnt != 0))) {
            asyncResponse.resume(new RestException(Status.PRECONDITION_FAILED, "Bookie 'rack' parameter is invalid, "
                + "When `RackawareEnsemblePlacementPolicy` is enabled, the rack name is not allowed to contain "
                + "slash (`/`) except for the beginning and end of the rack name string. "
                + "When `RegionawareEnsemblePlacementPolicy` is enabled, the rack name can only contain "
                + "one slash (`/`) except for the beginning and end of the rack name string."));
            return;
        }

        getPulsarResources().getBookieResources()
                .update(optionalBookiesRackConfiguration -> {

View on GitHub (pinned to 820761864e)

Solutions

1. Add the 'group' query parameter to the request, e.g. POST /admin/v2/bookies/rackInfo/{bookie}?group={group} with the BookieInfo JSON body.
2. In automation, validate that group is non-null before issuing the request and fail fast with a clear message.
3. Verify the rack name in the body also passes validation (no leading/trailing path separators) to avoid the next rejection.

Example fix

// before
curl -X POST 'http://broker:8080/admin/v2/bookies/rackInfo/bk1:3181' \
  -H 'Content-Type: application/json' -d '{"rack": "/dc1/rack1"}'

// after
curl -X POST 'http://broker:8080/admin/v2/bookies/rackInfo/bk1:3181?group=rg1' \
  -H 'Content-Type: application/json' -d '{"rack": "/dc1/rack1"}'

if (group == null || group.isEmpty()) {
    throw new IllegalArgumentException("'group' query parameter is required for bookie rack update");
}
admin.bookies().updateBookieRackInfo(bookie, group, new BookieInfo(rack));

When it happens

Trigger: POST to /admin/v2/bookies/rackInfo/{bookie} (updateBookieRackInfo) omitting the required 'group' query parameter while supplying a JSON body with the BookieInfo (rack), e.g. curl -X POST .../rackInfo/my-bookie:3181?group= missing entirely.

Common situations: Copy-pasted curl commands where ?group= was dropped; automation or UI built against an older API version that did not require group; mixing up 'group' with the rack field in the body; scripts written for the bookie rack update docs of a different Pulsar release.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Number of transaction coordinators should be more than the c
• Can not enable for all producers but denies for replicators,
• Error while scanning ledgers for ${namespaceName}
• ${loadManagerClass} does not support this operation
• Unauthorized to validateBothSuperuserAndBrokerOperation for

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