apache/rocketmq · error · MQClientException

maxSizeInBytes <= 0

Error message

maxSizeInBytes <= 0

What it means

Thrown by pullAsyncImpl when maxSizeInBytes (max cumulative message body size for one pull request) is zero or negative. This overload-level byte cap protects the client from oversized pull payloads and is validated before the request is issued.

Source

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

        final PullCallback pullCallback,
        final boolean block,
        final long timeout) throws MQClientException, RemotingException, 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);
        }

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


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

        this.subscriptionAutomatically(mq.getTopic());

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

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

            boolean isTagType = ExpressionType.isTagType(subscriptionData.getExpressionType());
            this.pullAPIWrapper.pullKernelImpl(
                mq,
                subscriptionData.getSubString(),

View on GitHub (pinned to 293f588571)

Solutions

1. Pass a positive byte cap, e.g. 10 * 1024 * 1024 (10 MiB) or DefaultMQPushConsumer's default pullThresholdSizePerQueue
2. Validate the config value at startup and fail fast if <= 0
3. Prefer the simpler pullAsync overloads unless byte capping is genuinely required

Example fix

// before
consumer.pullAsync(mq, "*", off, 32, 0, cb, false, 3000);

// after
int maxBytes = 10 * 1024 * 1024;
consumer.pullAsync(mq, "*", off, 32, maxBytes, cb, false, 3000);

int maxBytes = configuredMaxBytes > 0 ? configuredMaxBytes : 10 * 1024 * 1024;

When it happens

Trigger: Calling the pullAsync overload that takes maxSizeInBytes with a value <= 0; deriving the cap from a config property that defaults to 0; computing bytes-per-message * maxNums where either factor is zero.

Common situations: Applications setting consumer.setPullThresholdSizePerQueue(...) or a custom byte cap incorrectly; new async integrations copying the 8-arg overload without setting the size parameter.

Related errors

• offset < 0
• maxNums <= 0
• pullCallback is null
• pullAsync unknown exception
• Broker[{destBrokerName}] master node does not exist

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