apache/rocketmq · error · MQClientException

mq is null

Error message

mq is null

What it means

The internal pull path DefaultLitePullConsumerImpl.pullSyncImpl rejects a null MessageQueue with MQClientException("mq is null") before building the pull request. It surfaces through the public pull(MessageQueue, ...) APIs of DefaultLitePullConsumer when the caller passes a null queue (typically one that was never found in a lookup).

Source

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

    }

    private PullResult pull(MessageQueue mq, SubscriptionData subscriptionData, long offset, int maxNums)
        throws MQClientException, RemotingException, MQBrokerException, InterruptedException {
        return pull(mq, subscriptionData, offset, maxNums, this.defaultLitePullConsumer.getConsumerPullTimeoutMillis());
    }

    private PullResult pull(MessageQueue mq, SubscriptionData subscriptionData, long offset, int maxNums, long timeout)
        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(),

View on GitHub (pinned to 293f588571)

Solutions

1. Null-check the MessageQueue before calling pull
2. Filter nulls out of queue collections: queues.removeIf(Objects::isNull)
3. Log the lookup key when a queue is not found instead of propagating null

Example fix

// before
MessageQueue q = queueMap.get(brokerName);
PullResult pr = consumer.pull(q, "*", 0, 1, 3000);

// after
MessageQueue q = queueMap.get(brokerName);
if (q == null) throw new IllegalArgumentException("no queue for broker " + brokerName);
PullResult pr = consumer.pull(q, "*", 0, 1, 3000);

if (mq == null) throw new IllegalArgumentException("MessageQueue not resolved");
PullResult r = consumer.pull(mq, expr, offset, maxNums, timeout);

When it happens

Trigger: consumer.pull(null, subExpression, offset, maxNums); passing a queue variable whose lookup (e.g. map.get) returned null.

Common situations: Iterating a queue collection that contains nulls; a queue lookup keyed by broker name that misses.

Related errors

• mq is null
• messageModel is null
• offset < 0
• maxNums <= 0
• parse subscription error

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