apache/pulsar · error · RestException

maxConsumersPerSubscription must be 0 or more

Error message

maxConsumersPerSubscription must be 0 or more

What it means

Thrown by internalSetMaxConsumersPerSubscription when the provided value is negative. The per-subscription consumer limit must be null (unset) or >= 0. The broker rejects the change with HTTP 412 PRECONDITION_FAILED before persisting the policy.

Source

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

        } catch (RestException pfe) {
            throw pfe;
        } catch (Exception e) {
            log.error()
                    .attr("namespace", namespaceName)
                    .exception(e)
                    .log("Failed to update maxConsumersPerTopic configuration for namespace");
            throw new RestException(e);
        }
    }

    protected void internalSetMaxConsumersPerSubscription(Integer maxConsumersPerSubscription) {
        validateNamespacePolicyOperation(namespaceName, PolicyName.MAX_CONSUMERS, PolicyOperation.WRITE);
        validatePoliciesReadOnlyAccess();

        try {
            if (maxConsumersPerSubscription != null && maxConsumersPerSubscription < 0) {
                throw new RestException(Status.PRECONDITION_FAILED,
                        "maxConsumersPerSubscription must be 0 or more");
            }
            updatePolicies(namespaceName, policies -> {
                policies.max_consumers_per_subscription = maxConsumersPerSubscription;
                return policies;
            });
            log.info()
                    .attr("namespace", namespaceName)
                    .attr("maxConsumersPerSubscription", maxConsumersPerSubscription)
                    .log("Successfully updated maxConsumersPerSubscription configuration");
        } catch (RestException pfe) {
            throw pfe;
        } catch (Exception e) {
            log.error()
                    .attr("namespace", namespaceName)
                    .exception(e)
                    .log("Failed to update maxConsumersPerSubscription configuration");
            throw new RestException(e);

View on GitHub (pinned to 820761864e)

Solutions

1. Pass 0 or a positive integer
2. Use null/omit to clear the limit
3. Add a guard (value == null || value >= 0) in tooling that calls this endpoint

Example fix

// before
admin.namespaces().setMaxConsumersPerSubscription("my-tenant/my-ns", -1); // 412
// after
admin.namespaces().setMaxConsumersPerSubscription("my-tenant/my-ns", null); // unset
admin.namespaces().setMaxConsumersPerSubscription("my-tenant/my-ns", 10);

if (maxConsumersPerSubscription != null && maxConsumersPerSubscription < 0) {
    throw new IllegalArgumentException("maxConsumersPerSubscription must be >= 0 or null");
}

boolean isValidCount(Integer v) { return v == null || v >= 0; }

try {
    admin.namespaces().setMaxConsumersPerSubscription(ns, maxConsumersPerSubscription);
} catch (PulsarAdminException.PreconditionFailedException e) {
    log.error("Negative maxConsumersPerSubscription rejected: use null for unlimited");
    throw e;
}

When it happens

Trigger: POST /namespaces/{ns}/maxConsumersPerSubscription with a negative integer; using -1 intending 'unlimited' rather than null; config pipelines substituting an empty value with a negative default.

Common situations: Same sentinel confusion as other count-based policies (-1 = unlimited from other ecosystems); generated policy JSON with invalid defaults; manual typos in CLI invocations.

Related errors

• Subscription has active connected consumers
• maxConsumersPerTopic must be 0 or more
• Topic name is not valid
• Partitioned Topic Name should not contain '-partition-'
• Invalid value for message TTL

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