apache/pulsar · error · RestException

RestException(e)

Error message

RestException(e)

What it means

A generic RestException wrapping any unexpected Exception thrown while updating a resource group's configuration (internalUpdateResourceGroup, invoked from the create-or-update path). Not-found and validation errors are rethrown earlier; anything else (usually a metadata store write failure) is logged as 'Failed to update configuration for ResourceGroup' and rethrown as a 500 RestException. The wrapped cause in the broker log holds the real problem.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/ResourceGroupsBase.java:92

                resourceGroup.setDispatchRateInMsgs(rgConfig.getDispatchRateInMsgs());
            }
            if (rgConfig.getDispatchRateInBytes() != null) {
                resourceGroup.setDispatchRateInBytes(rgConfig.getDispatchRateInBytes());
            }

            // write back the new ResourceGroup config.
            resourceGroupResources().updateResourceGroup(rgName, r -> resourceGroup);
            log.info()
                    .attr("resourceGroup", rgName)
                    .log("Successfully updated the ResourceGroup");
        } catch (RestException pfe) {
            throw pfe;
        } catch (Exception e) {
            log.error()
                    .attr("resourceGroup", rgName)
                    .exception(e)
                    .log("Failed to update configuration for ResourceGroup");
            throw new RestException(e);
        }
    }

    protected void internalCreateResourceGroup(String rgName, ResourceGroup rgConfig) {
        rgConfig.setPublishRateInMsgs(rgConfig.getPublishRateInMsgs() == null
                ? -1 : rgConfig.getPublishRateInMsgs());
        rgConfig.setPublishRateInBytes(rgConfig.getPublishRateInBytes() == null
                ? -1 : rgConfig.getPublishRateInBytes());
        rgConfig.setDispatchRateInMsgs(rgConfig.getDispatchRateInMsgs() == null
                ? -1 : rgConfig.getDispatchRateInMsgs());
        rgConfig.setDispatchRateInBytes(rgConfig.getDispatchRateInBytes() == null
                ? -1 : rgConfig.getDispatchRateInBytes());
        try {
            resourceGroupResources().createResourceGroup(rgName, rgConfig);
            log.info().attr("resourceGroup", rgName).log("Created ResourceGroup");
        } catch (MetadataStoreException.AlreadyExistsException e) {
            log.warn()
                    .attr("resourceGroup", rgName)

View on GitHub (pinned to 820761864e)

Solutions

1. Check the broker log 'Failed to update configuration for ResourceGroup' for the wrapped cause.
2. Verify metadata store health and retry after the store recovers.
3. Validate publish/dispatch rate fields (non-negative where required) before issuing the update.
4. Retry the update; if conflicts persist, serialize writes to the same resource group.

Example fix

// before
admin.resourcegroups().updateResourceGroup(rgName, rg); // opaque 500
// after
try {
    admin.resourcegroups().updateResourceGroup(rgName, rg);
} catch (PulsarAdminException e) {
    log.error("Update of resource group {} failed", rgName, e); // see broker log cause
    throw e;
}

// validate before calling
if (rg.getPublishRateInMsgs() != null && rg.getPublishRateInMsgs() < -1)
    throw new IllegalArgumentException("invalid publishRateInMsgs");

null

try {
    admin.resourcegroups().updateResourceGroup(rgName, rg);
} catch (PulsarAdminException e) {
    if (e.getStatusCode() >= 500) retryWithBackoff();
    else throw e;
}

When it happens

Trigger: PUT /admin/v3/resourcegroups/{rgName} (or internalCreateOrUpdateResourceGroup choosing update) when the metadata store put/compare-and-set fails, the store session expires mid-write, or an unexpected exception occurs during validation of rate limits.

Common situations: Config-store write timeouts during cluster churn; ZooKeeper session loss; concurrent writers causing CAS conflicts surfaced as generic exceptions; invalid quota values that slipped past pre-validation.

Related errors

• e
• Concurrent modification
• ResourceGroup already exists
• ResourceGroup is in use
• RestException(e)

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