apache/pulsar · error · PulsarAdminException

incrementUsage on tenant=%s, NS=%s: bytes (%s) or mesgs (%s)

Error message

incrementUsage on tenant=%s, NS=%s: bytes (%s) or mesgs (%s) is negative

What it means

incrementUsage validates the usage delta before applying it: either the byte count or message count was negative, which is impossible for a usage increment and would corrupt the resource-group accounting, so the update is refused.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/resourcegroup/ResourceGroupService.java:370

     * @param nsName
     * @param monClass
     * @param incStats
     * @returns true if the stats were updated; false if nothing was updated.
     */
    protected boolean incrementUsage(String tenantName, String nsName,
                                  ResourceGroupMonitoringClass monClass,
                                  BytesAndMessagesCount incStats) throws PulsarAdminException {
        final ResourceGroup nsRG = this.namespaceToRGsMap.get(NamespaceName.get(tenantName, nsName));
        final ResourceGroup tenantRG = this.tenantToRGsMap.get(tenantName);
        if (tenantRG == null && nsRG == null) {
            return false;
        }

        // Expect stats to increase monotonically.
        if (incStats.bytes < 0 || incStats.messages < 0) {
            String errMesg = String.format("incrementUsage on tenant=%s, NS=%s: bytes (%s) or mesgs (%s) is negative",
                    tenantName, nsName, incStats.bytes, incStats.messages);
            throw new PulsarAdminException(errMesg);
        }

        if (nsRG == tenantRG) {
            // Update only once in this case.
            // Note that we will update both tenant and namespace RGs in other cases.
            nsRG.incrementLocalUsageStats(monClass, incStats);
            rgLocalUsageMessages.labels(nsRG.resourceGroupName, monClass.name()).inc(incStats.messages);
            rgLocalUsageBytes.labels(nsRG.resourceGroupName, monClass.name()).inc(incStats.bytes);
            return true;
        }

        if (tenantRG != null) {
            tenantRG.incrementLocalUsageStats(monClass, incStats);
            rgLocalUsageMessages.labels(tenantRG.resourceGroupName, monClass.name()).inc(incStats.messages);
            rgLocalUsageBytes.labels(tenantRG.resourceGroupName, monClass.name()).inc(incStats.bytes);
        }
        if (nsRG != null) {
            nsRG.incrementLocalUsageStats(monClass, incStats);

View on GitHub (pinned to 820761864e)

Solutions

1. Fix the caller to report non-negative byte/message deltas
2. Check for integer overflow or double-counted decrements in the stats pipeline

When it happens

Trigger: Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/resourcegroup/ResourceGroupService.java:370 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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