apache/rocketmq · error · MQClientException

messageModel is null

Error message

messageModel is null

What it means

MQClientException from DefaultLitePullConsumerImpl.checkConfig during start(): messageModel is null. The clustering/broadcasting model must be set (a default normally exists), so a null model means code explicitly set it to null or a custom builder cleared it.

Source

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

    }

    private void checkConfig() throws MQClientException {
        // Check consumerGroup
        Validators.checkGroup(this.defaultLitePullConsumer.getConsumerGroup());

        // Check consumerGroup name is not equal default consumer group name.
        if (this.defaultLitePullConsumer.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);
        }

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

View on GitHub (pinned to 293f588571)

Solutions

1. Set the model explicitly: consumer.setMessageModel(MessageModel.CLUSTERING) (or BROADCASTING)
2. Fix the property binding so absent values fall back to a default rather than null
3. Validate required config fields at application startup before creating the consumer

Example fix

// before: @Value missing -> null injected
consumer.setMessageModel(props.getMessageModel()); // null when property absent

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

if (consumer.getMessageModel() == null) {
    consumer.setMessageModel(MessageModel.CLUSTERING);
}

When it happens

Trigger: Calling consumer.setMessageModel(null) (possibly via property binding that maps a missing config value to null) and then start(). Spring @Value or YAML-backed fields defaulting to null when the key is absent are a typical source.

Common situations: Configuration binding that injects null for a missing/misspelled messageModel property; test code copying constructor patterns from classes where the field was deliberately nulled; serialization frameworks restoring a consumer config without the model field.

Related errors

• consumerGroup can not equal
• allocateMessageQueueStrategy 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/35870fa3d4a42e93. Report an issue: GitHub.