apache/rocketmq · error · MQClientException

messageModel is null

Error message

messageModel is null

What it means

checkConfig() requires a MessageModel (CLUSTERING or BROADCASTING) on the consumer. DefaultMQPushConsumer normally initializes messageModel to CLUSTERING, so a null value means something explicitly set it to null before start().

Source

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

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

        if (this.defaultMQPushConsumer.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);
        }

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

        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);

View on GitHub (pinned to 293f588571)

Solutions

1. Do not call setMessageModel(null); pick CLUSTERING (default, load-balanced) or BROADCASTING explicitly
2. Fix the config binder so invalid enum values throw instead of producing null
3. Set the model explicitly in your consumer factory so intent is obvious

Example fix

// before
consumer.setMessageModel(null); // e.g. bad enum binding

// after
consumer.setMessageModel(MessageModel.CLUSTERING); // or BROADCASTING, explicitly

MessageModel model = config.getModel() != null ? config.getModel() : MessageModel.CLUSTERING;
consumer.setMessageModel(model);

boolean isValidMessageModel(MessageModel m) { return m == MessageModel.CLUSTERING || m == MessageModel.BROADCASTING; }

When it happens

Trigger: Calling setMessageModel(null); a mapping layer (DI, config binder) assigning null when the configured string does not match a property and binds null instead of failing.

Common situations: Custom config binding that converts an unknown enum string to null; test code constructing the consumer with reflection/mocks that leave messageModel null; framework deserialization of consumer settings.

Related errors

• consumerGroup can not equal
• messageModel is null
• consumerGroup is null
• consumeFromWhere is null
• allocateMessageQueueStrategy is null

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