apache/rocketmq · error · MQClientException

Long polling mode, the consumer consumerTimeoutMillisWhenSus

Error message

Long polling mode, the consumer consumerTimeoutMillisWhenSuspend must greater than brokerSuspendMaxTimeMillis

What it means

Thrown by checkConfig() during start() when consumerTimeoutMillisWhenSuspend < brokerSuspendMaxTimeMillis. In long-polling (blocking) pull mode the broker holds the request up to brokerSuspendMaxTimeMillis; the client must be willing to wait at least that long or every blocked pull would client-side-timeout while the broker is still validly suspended.

Source

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

        // 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) {
                for (final String topic : registerTopics) {
                    SubscriptionData subscriptionData = FilterAPI.buildSubscriptionData(topic, SubscriptionData.SUB_ALL);
                    this.rebalanceImpl.getSubscriptionInner().put(topic, subscriptionData);
                }
            }
        } catch (Exception e) {
            throw new MQClientException("subscription exception", e);
        }

View on GitHub (pinned to 293f588571)

Solutions

1. Keep consumerTimeoutMillisWhenSuspend strictly >= brokerSuspendMaxTimeMillis, e.g. broker 20_000 with consumer timeout 25_000
2. If you want short waits, lower BOTH values together, keeping the invariant
3. Avoid block=true pulls entirely (use non-blocking pull with a small timeout) if you do not want long polling

Example fix

// before
consumer.setBrokerSuspendMaxTimeMillis(20_000);
consumer.setConsumerTimeoutMillisWhenSuspend(5_000); // violates invariant
consumer.start();

// after
consumer.setBrokerSuspendMaxTimeMillis(20_000);
consumer.setConsumerTimeoutMillisWhenSuspend(25_000);
consumer.start();

if (consumerTimeoutMillisWhenSuspend < brokerSuspendMaxTimeMillis) {
    throw new IllegalStateException("consumerTimeoutMillisWhenSuspend must be >= brokerSuspendMaxTimeMillis");
}

When it happens

Trigger: Calling consumer.setConsumerTimeoutMillisWhenSuspend(n) or setBrokerSuspendMaxTimeMillis(m) such that n < m before start(); lowering the consumer timeout (e.g. to 5s) while brokerSuspendMaxTimeMillis stays at its default 40s; raising brokerSuspendMaxTimeMillis above the consumer timeout.

Common situations: Tuning timeouts to make pulls fail fast without realizing the blocking pull path enforces this invariant; defaults are consistent (consumer timeout 15s vs... in DefaultMQPullConsumer defaults are brokerSuspendMaxTimeMillis=20s and consumerTimeoutMillisWhenSuspend=15s only in push consumer — pull consumer defaults keep the invariant), so this fires after manual tuning.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

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