apache/pulsar · error · RestException

maxUnackedMessagesPerConsumer must be 0 or more

Error message

maxUnackedMessagesPerConsumer must be 0 or more

What it means

Raised by the namespace admin API when setting maxUnackedMessagesPerConsumer to a negative value; the guard rejects the policy update before any persistence happens, returning 412 Precondition Failed.

Source

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

                    .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);
        }
    }

    protected void internalSetMaxUnackedMessagesPerConsumer(Integer maxUnackedMessagesPerConsumer) {
        validateNamespacePolicyOperation(namespaceName, PolicyName.MAX_UNACKED, PolicyOperation.WRITE);
        validatePoliciesReadOnlyAccess();
        if (maxUnackedMessagesPerConsumer != null && maxUnackedMessagesPerConsumer < 0) {
            throw new RestException(Status.PRECONDITION_FAILED,
                    "maxUnackedMessagesPerConsumer must be 0 or more");
        }
        try {
            updatePolicies(namespaceName, policies -> {
                policies.max_unacked_messages_per_consumer = maxUnackedMessagesPerConsumer;
                return policies;
            });
            log.info()
                    .attr("namespace", namespaceName)
                    .attr("maxUnackedMessagesPerConsumer", maxUnackedMessagesPerConsumer)
                    .log("Successfully updated maxUnackedMessagesPerConsumer configuration");

        } catch (RestException pfe) {
            throw pfe;
        } catch (Exception e) {
            log.error()
                    .attr("namespace", namespaceName)
                    .exception(e)

View on GitHub (pinned to 820761864e)

Solutions

1. Pass 0 or a positive integer for maxUnackedMessagesPerConsumer; 0 disables the limit
2. Remove the negative value from the REST/CLI request payload

When it happens

Trigger: Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/NamespacesBase.java:2544 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/5c093d932df5cc74. Report an issue: GitHub.