apache/rocketmq · error · MQClientException

allocateMessageQueueStrategy is null

Error message

allocateMessageQueueStrategy is null

What it means

MQClientException from DefaultLitePullConsumerImpl.checkConfig during start(): allocateMessageQueueStrategy is null. This strategy distributes queues among group members during rebalance; the constructor normally installs a default (AllocateMessageQueueAveragely), so a null means it was explicitly cleared — usually by custom construction or reflection-based config.

Source

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

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

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

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

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

    public PullAPIWrapper getPullAPIWrapper() {
        return pullAPIWrapper;
    }

    private void startPullTask(Collection<MessageQueue> mqSet) {

View on GitHub (pinned to 293f588571)

Solutions

1. Do not null the strategy; rely on the constructor default or set one explicitly: consumer.setAllocateMessageQueueStrategy(new AllocateMessageQueueAveragely())
2. Fix config binding to keep the default when the property is missing
3. Add a startup assertion that core consumer settings are non-null before start()

Example fix

// before
consumer.setAllocateMessageQueueStrategy(
    props.getStrategy()); // null when not configured
consumer.start();

// after
AllocateMessageQueueStrategy s = Optional.ofNullable(props.getStrategy())
    .orElseGet(AllocateMessageQueueAveragely::new);
consumer.setAllocateMessageQueueStrategy(s);
consumer.start();

if (consumer.getAllocateMessageQueueStrategy() == null) {
    consumer.setAllocateMessageQueueStrategy(new AllocateMessageQueueAveragely());
}

When it happens

Trigger: Calling consumer.setAllocateMessageQueueStrategy(null) (directly or via a config binder injecting null) and then start(). Also possible with custom factory/builder code that sets fields via reflection and skips the strategy.

Common situations: Config binding with an optional allocate strategy key that maps to null when absent; DI frameworks creating the consumer via a nonstandard constructor path that bypasses defaults; partial copies of producer/consumer config objects.

Related errors

• consumerGroup can not equal
• messageModel is null
• Long polling mode, the consumer consumerTimeoutMillisWhenSus
• The consumer not running, please start it first.
• Subscribe and assign are mutually exclusive.

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