apache/rocketmq · error · MQClientException

allocateMessageQueueStrategy is null

Error message

allocateMessageQueueStrategy is null

What it means

checkConfig() requires an AllocateMessageQueueStrategy — the algorithm that splits queues among consumer instances in a group (e.g. AllocateMessageQueueAveragely). The field defaults to a valid strategy, so null means it was explicitly cleared or bypassed via reflection/mocking.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java:1068

        if (null == this.defaultMQPushConsumer.getConsumeFromWhere()) {
            throw new MQClientException(
                "consumeFromWhere is null"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

        Date dt = UtilAll.parseDate(this.defaultMQPushConsumer.getConsumeTimestamp(), UtilAll.YYYYMMDDHHMMSS);
        if (null == dt) {
            throw new MQClientException(
                "consumeTimestamp is invalid, the valid format is yyyyMMddHHmmss,but received "
                    + this.defaultMQPushConsumer.getConsumeTimestamp()
                    + " " + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL), null);
        }

        // allocateMessageQueueStrategy
        if (null == this.defaultMQPushConsumer.getAllocateMessageQueueStrategy()) {
            throw new MQClientException(
                "allocateMessageQueueStrategy is null"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

        // subscription
        if (null == this.defaultMQPushConsumer.getSubscription()) {
            throw new MQClientException(
                "subscription is null"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

        // messageListener
        if (null == this.defaultMQPushConsumer.getMessageListener()) {
            throw new MQClientException(
                "messageListener is null"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),

View on GitHub (pinned to 293f588571)

Solutions

1. Do not set the strategy to null; omit the setter call to keep the default AllocateMessageQueueAveragely
2. If injecting a custom strategy, ensure the bean is non-null before assignment and fail fast otherwise
3. In tests, build a real DefaultMQPushConsumer rather than a partial mock

Example fix

// before
consumer.setAllocateMessageQueueStrategy(null);

// after
// omit the call entirely (default), or:
consumer.setAllocateMessageQueueStrategy(new AllocateMessageQueueAveragely());

AllocateMessageQueueStrategy s = strategy != null ? strategy : new AllocateMessageQueueAveragely();
consumer.setAllocateMessageQueueStrategy(s);

When it happens

Trigger: Calling setAllocateMessageQueueStrategy(null); constructing the impl object directly in tests with mocks that return null from the getter.

Common situations: Unit tests mocking DefaultMQPushConsumer; config copy code that assigns every field including nulls; custom strategy injection where the custom bean failed to initialize and null was passed.

Related errors

• currentCID is empty
• mqAll is null or mqAll empty
• cidAll is null or cidAll empty
• consumerGroup can not equal
• allocateMessageQueueStrategy is null

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