apache/pulsar · error · RestException

maxUnackedMessagesPerSubscription must be 0 or more

Error message

maxUnackedMessagesPerSubscription must be 0 or more

What it means

Guard in the maxUnackedMessagesPerSubscription setter: a negative value was passed for the namespace anti-backlog limit, so the update is rejected with 412 Precondition Failed before policies are persisted; zero disables the cap and positive values set it.

Source

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

            throw new RestException(e);
        }
    }

    protected void internalSetMaxSubscriptionsPerTopic(Integer maxSubscriptionsPerTopic){
        validateNamespacePolicyOperation(namespaceName, PolicyName.MAX_SUBSCRIPTIONS, PolicyOperation.WRITE);
        validatePoliciesReadOnlyAccess();
        if (maxSubscriptionsPerTopic != null && maxSubscriptionsPerTopic < 0) {
            throw new RestException(Status.PRECONDITION_FAILED,
                    "maxSubscriptionsPerTopic must be 0 or more");
        }
        internalSetPolicies("max_subscriptions_per_topic", maxSubscriptionsPerTopic);
    }

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

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

View on GitHub (pinned to 820761864e)

Solutions

1. Use a non-negative integer (0 means no limit) for maxUnackedMessagesPerSubscription
2. Check the request body for a sign error or corrupted numeric field

When it happens

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