apache/rocketmq · error · MQClientException

allocateMessageQueueStrategy is null

Error message

allocateMessageQueueStrategy is null

What it means

Thrown by checkConfig() during start() when allocateMessageQueueStrategy is null. The allocation strategy decides how queues are distributed among consumers in a group during rebalance; the pull consumer implementation requires one to be configured even though pull consumers often use manual allocation.

Source

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

            throw new MQClientException(
                "consumerGroup can not equal "
                    + MixAll.DEFAULT_CONSUMER_GROUP
                    + ", please specify another one."
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

        // messageModel
        if (null == this.defaultMQPullConsumer.getMessageModel()) {
            throw new MQClientException(
                "messageModel is null"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

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

        // allocateMessageQueueStrategy
        if (this.defaultMQPullConsumer.getConsumerTimeoutMillisWhenSuspend() < this.defaultMQPullConsumer.getBrokerSuspendMaxTimeMillis()) {
            throw new MQClientException(
                "Long polling mode, the consumer consumerTimeoutMillisWhenSuspend must greater than brokerSuspendMaxTimeMillis"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }
    }

    private void copySubscription() throws MQClientException {
        try {
            Set<String> registerTopics = this.defaultMQPullConsumer.getRegisterTopics();
            if (registerTopics != null) {

View on GitHub (pinned to 293f588571)

Solutions

1. Set the strategy explicitly: consumer.setAllocateMessageQueueStrategy(new AllocateMessageQueueAveragely())
2. Remove config-driven null assignment; validate the property resolves to a real strategy instance
3. For manual/assigned pull patterns use AllocateMessageQueueByConfig with your fixed queue list

Example fix

// before
consumer.setAllocateMessageQueueStrategy(strategy); // strategy null
consumer.start();

// after
AllocateMessageQueueStrategy strategy =
    strategyFromConfig != null ? strategyFromConfig : new AllocateMessageQueueAveragely();
consumer.setAllocateMessageQueueStrategy(strategy);
consumer.start();

if (strategy == null) strategy = new AllocateMessageQueueAveragely();

When it happens

Trigger: setAllocateMessageQueueStrategy(null) before start(); constructing the impl layer directly (DefaultMQPullConsumerImpl) without propagating the default strategy from the facade class.

Common situations: Like messageModel, DefaultMQPullConsumer normally defaults this field (AllocateMessageQueueAveragely); hitting the error implies explicit nulling — typically a config binder or a test constructing the consumer via a path that skips field defaults.

Related errors

• allocateMessageQueueStrategy is null
• consumerGroup is null
• consumerGroup can not equal {DEFAULT_CONSUMER_GROUP}, please
• messageModel is null
• Long polling mode, the consumer consumerTimeoutMillisWhenSus

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