apache/rocketmq · warning · MQClientException

Check client in broker error, maybe because you use {express

Error message

Check client in broker error, maybe because you use {expressionType} to filter message, but server has not been upgraded to support!This error would not affect the launch of consumer, but may has impact on message receiving if you have use the new features which are not supported by server, please check the log!

What it means

Thrown when the consumer's pre-subscription check (checkClientInBroker) fails against a broker because the subscription's filter expression type (e.g. SQL92 or the ENCODED class-filter mode) is not supported by that broker. This happens when the client is newer than the broker: the client advertises an expressionType the broker cannot parse, so the broker rejects the check-client request. The message itself states it does not block consumer startup, but message receiving with the unsupported filter will be impacted.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/factory/MQClientInstance.java:559

            for (SubscriptionData subscriptionData : subscriptionInner) {
                if (ExpressionType.isTagType(subscriptionData.getExpressionType())) {
                    continue;
                }
                // may need to check one broker every cluster...
                // assume that the configs of every broker in cluster are the same.
                String addr = findBrokerAddrByTopic(subscriptionData.getTopic());

                if (addr != null) {
                    try {
                        this.getMQClientAPIImpl().checkClientInBroker(
                            addr, entry.getKey(), this.clientId, subscriptionData, clientConfig.getMqClientApiTimeout()
                        );
                    } catch (Exception e) {
                        if (e instanceof MQClientException) {
                            throw (MQClientException) e;
                        } else {
                            throw new MQClientException("Check client in broker error, maybe because you use "
                                + subscriptionData.getExpressionType() + " to filter message, but server has not been upgraded to support!"
                                + "This error would not affect the launch of consumer, but may has impact on message receiving if you " +
                                "have use the new features which are not supported by server, please check the log!", e);
                        }
                    }
                }
            }
        }
    }

    public boolean sendHeartbeatToAllBrokerWithLockV2(boolean isRebalance) {
        if (this.lockHeartbeat.tryLock()) {
            try {
                if (clientConfig.isUseHeartbeatV2()) {
                    return this.sendHeartbeatToAllBrokerV2(isRebalance);
                } else {
                    return this.sendHeartbeatToAllBroker();
                }

View on GitHub (pinned to 293f588571)

Solutions

1. Upgrade all brokers in the cluster to a version that supports your expression type (>=4.4 for SQL92), then restart the consumer
2. If you cannot upgrade, change the subscription back to a compatible expression type (TAG filtering) on both producer and consumer
3. Verify broker versions with 'sh mqadmin clusterList -n <nameserver>' and make sure every broker listed for the topic supports the filter
4. Set a longer-term policy: pin client jar version to match the oldest broker in the cluster until the upgrade completes

Example fix

// before
consumer.subscribe(topic, MessageSelector.bySql("a > 5")); // SQL92 against old broker
// after
consumer.subscribe(topic, "TagA"); // TAG filtering, supported by all brokers

// before start(): check broker compatibility if using SQL92
// (no direct client API; guard by version policy)
String expr = consumer.getMessageModel() == null ? null : mySelectorType;
// simplest guard: only use SQL92 when broker version known >= 4.4
boolean sql92Supported = brokerVersion >= BrokerVersion.V4_4_0;
if (!sql92Supported) consumer.subscribe(topic, "*"); // TAG mode
else consumer.subscribe(topic, MessageSelector.bySql("a > 5"));

try {
    consumer.start();
} catch (MQClientException e) {
    if (e.getMessage() != null && e.getMessage().contains("Check client in broker error")) {
        log.warn("Filter type unsupported by broker; falling back to TAG filtering", e);
        // re-subscribe with TAG, restart consumer
    } else throw e;
}

When it happens

Trigger: Calling consumer.start() (which triggers MQClientInstance.checkClientInBroker) with a SubscriptionData whose expressionType is EXPRESSION_TYPE_SQL92 while at least one broker in the topic's cluster runs an old version without SQL92 filter support; also using TAG or ENCODED expression types against brokers that never implemented them. Any non-MQClientException thrown by checkClientInBroker(addr, consumerGroup, clientId, subscriptionData, timeout) is wrapped into this error.

Common situations: Mixed-version cluster during a rolling upgrade (old brokers still serving the topic); using a new client jar (4.x/5.x) against a 3.x broker; switching from tag filtering to SQL92 filtering without upgrading brokers first.

Related errors

• The consumer not running, please start it first.
• Subscribe and assign are mutually exclusive.
• The PullConsumer service state not OK, maybe started once,
• The consumer group[
• consumerGroup can not equal

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