apache/rocketmq · error · MQClientException

maxNums <= 0

Error message

maxNums <= 0

What it means

pullSyncImpl throws MQClientException("maxNums <= 0") when the batch size argument is zero or negative. maxNums bounds how many messages the broker may return in one pull; a non-positive value would request nothing and is rejected before the network call.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultLitePullConsumerImpl.java:1055

        throws MQClientException, RemotingException, MQBrokerException, InterruptedException {
        return this.pullSyncImpl(mq, subscriptionData, offset, maxNums, true, timeout);
    }

    private PullResult pullSyncImpl(MessageQueue mq, SubscriptionData subscriptionData, long offset, int maxNums,
        boolean block,
        long timeout)
        throws MQClientException, RemotingException, MQBrokerException, InterruptedException {

        if (null == mq) {
            throw new MQClientException("mq is null", null);
        }

        if (offset < 0) {
            throw new MQClientException("offset < 0", null);
        }

        if (maxNums <= 0) {
            throw new MQClientException("maxNums <= 0", null);
        }

        int sysFlag = PullSysFlag.buildSysFlag(false, block, true, false, true);

        long timeoutMillis = block ? this.defaultLitePullConsumer.getConsumerTimeoutMillisWhenSuspend() : timeout;

        boolean isTagType = ExpressionType.isTagType(subscriptionData.getExpressionType());
        PullResult pullResult = this.pullAPIWrapper.pullKernelImpl(
            mq,
            subscriptionData.getSubString(),
            subscriptionData.getExpressionType(),
            isTagType ? 0L : subscriptionData.getSubVersion(),
            offset,
            maxNums,
            sysFlag,
            0,
            this.defaultLitePullConsumer.getBrokerSuspendMaxTimeMillis(),
            timeoutMillis,

View on GitHub (pinned to 293f588571)

Solutions

1. Default the batch size to a positive value (e.g. 32) in configuration
2. Clamp: Math.max(1, configuredBatchSize) before calling pull

Example fix

// before
consumer.pull(q, "*", offset, config.getPullBatch(), 3000); // getPullBatch() may return 0

// after
int batch = Math.max(1, config.getPullBatch());
consumer.pull(q, "*", offset, batch, 3000);

int batch = Math.max(1, configuredPullBatchSize);
PullResult r = consumer.pull(mq, expr, offset, batch, timeout);

When it happens

Trigger: consumer.pull(q, expr, offset, 0, timeout); passing a configurable pull batch size that defaults to 0 when unset.

Common situations: Batch size read from config with a missing default; arithmetic that divides/multiplies down to 0.

Related errors

• offset < 0
• consumerGroup can not equal
• Topic can not be null or empty.
• Message queues can not be null or empty.
• subExpression can not be null or empty.

AI-assisted analysis of apache/rocketmq@293f588571 (2026-08-14). Data as JSON: /api/errors/cef0f8050f7b4638. Report an issue: GitHub.