apache/rocketmq · error · MQClientException

messageModel is null

Error message

messageModel is null

What it means

Thrown by checkConfig() during start() when messageModel is null. The message model (CLUSTERING vs BROADCASTING) determines how queues are allocated and offsets are stored; the implementation requires it to be explicitly present at start time.

Source

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

            throw new MQClientException(
                "consumerGroup is null"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

        // consumerGroup
        if (this.defaultMQPullConsumer.getConsumerGroup().equals(MixAll.DEFAULT_CONSUMER_GROUP)) {
            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),

View on GitHub (pinned to 293f588571)

Solutions

1. Set the model explicitly: consumer.setMessageModel(MessageModel.CLUSTERING) (or BROADCASTING as needed)
2. Fix the config binding so invalid enum strings fail at load time rather than binding null
3. Remove any code path that assigns null to messageModel

Example fix

// before
consumer.setMessageModel(modelFromConfig); // null when unparsable
consumer.start();

// after
MessageModel model = modelFromConfig != null ? modelFromConfig : MessageModel.CLUSTERING;
consumer.setMessageModel(model);
consumer.start();

if (model == null) model = MessageModel.CLUSTERING; consumer.setMessageModel(model);

When it happens

Trigger: setMessageModel(null) before start(); a reflection/config binder that sets the field to null when the property string is empty; deserializing consumer config where the enum failed to parse.

Common situations: Note DefaultMQPullConsumer normally defaults messageModel to MessageModel.CLUSTERING in its field initializer, so hitting this usually means code explicitly nulled it — commonly a Spring @ConfigurationProperties binding of an invalid enum value that resolves to null.

Related errors

• consumerGroup is null
• The consumer group[{consumerGroup}] has been created before,
• The PullConsumer service state not OK, maybe started once, {
• consumerGroup can not equal {DEFAULT_CONSUMER_GROUP}, please
• allocateMessageQueueStrategy is null

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