apache/rocketmq · error · MQClientException

maxNums <= 0

Error message

maxNums <= 0

What it means

Thrown by pullSyncImpl when maxNums (max number of messages per pull request) is zero or negative. The value is forwarded to the pull kernel as the batch size; anything <= 0 would ask the broker for no or a nonsensical number of messages.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPullConsumerImpl.java:243

            throw new MQClientException("parse subscription error", e);
        }
    }

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

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

        this.subscriptionAutomatically(mq.getTopic());

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

        long timeoutMillis = block ? this.defaultMQPullConsumer.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,

View on GitHub (pinned to 293f588571)

Solutions

1. Set a positive batch size, typically 32 (a common default) via consumer.setPullBatchSize(...) or the literal argument
2. Validate configuration at startup: fail fast if the configured pull size is < 1
3. If a 'no limit' semantic is wanted, clamp to a sane upper bound like 1000 rather than passing 0

Example fix

// before
int maxNums = config.getPullBatchSize(); // 0 when unset
consumer.pull(mq, "*", offset, maxNums);

// after
int maxNums = Math.max(1, config.getPullBatchSize());
consumer.pull(mq, "*", offset, maxNums);

int batch = Math.max(1, configuredBatchSize);

When it happens

Trigger: DefaultMQPullConsumer.pull(mq, expr, offset, maxNums) with maxNums = 0 or negative; batch size read from configuration that defaults to 0 when unset; passing a computed pullSize that underflows.

Common situations: Configuring pullBatchSize to 0 in application properties; reusing a 'limit' variable that is 0 when the caller wants 'unlimited'; copying quick-start code that forgot to set the batch size.

Related errors

• offset < 0
• maxSizeInBytes <= 0
• maxNums <= 0
• pullCallback is null
• pullAsync unknown exception

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