apache/rocketmq · error · MQClientException

subscription exception

Error message

subscription exception

What it means

A generic MQClientException ('subscription exception') wrapping whatever failure occurred inside copySubscription(), which runs during consumer start. copySubscription copies user subscriptions into the rebalance table and, in CLUSTERING mode, also builds the retry-topic subscription via FilterAPI.buildSubscriptionData. The wrapped cause carries the real reason — almost always an invalid topic or subscription expression.

Source

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

            }

            if (null == this.messageListenerInner) {
                this.messageListenerInner = this.defaultMQPushConsumer.getMessageListener();
            }

            switch (this.defaultMQPushConsumer.getMessageModel()) {
                case BROADCASTING:
                    break;
                case CLUSTERING:
                    final String retryTopic = MixAll.getRetryTopic(this.defaultMQPushConsumer.getConsumerGroup());
                    SubscriptionData subscriptionData = FilterAPI.buildSubscriptionData(retryTopic, SubscriptionData.SUB_ALL);
                    this.rebalanceImpl.getSubscriptionInner().put(retryTopic, subscriptionData);
                    break;
                default:
                    break;
            }
        } catch (Exception e) {
            throw new MQClientException("subscription exception", e);
        }
    }

    public MessageListener getMessageListenerInner() {
        return messageListenerInner;
    }

    private void updateTopicSubscribeInfoWhenSubscriptionChanged() {
        if (doNotUpdateTopicSubscribeInfoWhenSubscriptionChanged) {
            return;
        }
        Map<String, SubscriptionData> subTable = this.getSubscriptionInner();
        if (subTable != null) {
            for (final Map.Entry<String, SubscriptionData> entry : subTable.entrySet()) {
                final String topic = entry.getKey();
                this.mQClientFactory.updateTopicRouteInfoFromNameServer(topic);
            }
        }

View on GitHub (pinned to 293f588571)

Solutions

1. Inspect the cause (e.getCause()) of the MQClientException — it names the exact invalid topic or expression
2. Validate topic names against ^[%|a-zA-Z0-9_-]+$ and subscription expressions before calling subscribe()
3. Sanitize the consumer group name: it is embedded in %RETRY%<group> and must form a legal topic name
4. Ensure the subscription string is either '*' or a well-formed 'TagA || TagB' expression

Example fix

// before
consumer.subscribe("order topic", "TagA ||"); // trailing operator: parse fails inside start()
// after
consumer.subscribe("orderTopic", "TagA || TagB");
// and pre-validate:
// TopicValidator.validateTopic(topic); FilterAPI.buildSubscriptionData(topic, expr); // dry-run parse

TopicValidator.validateTopic(topic);
FilterAPI.buildSubscriptionData(topic, expr); // dry-run parse before start()
if (!consumer.getMessageModel().name().matches("BROADCASTING|CLUSTERING")) throw new IllegalArgumentException("bad model");

try { consumer.start(); } catch (MQClientException e) { Throwable c = e.getCause(); log.error("subscription build failed: {}", c, e instanceof MQClientException ? c.getMessage() : e); /* fix topic/expr, rebuild consumer */ }

When it happens

Trigger: consumer.start() with a subscription previously registered via DefaultMQPushConsumer.subscribe(topic, subExpression) where the topic contains illegal characters or the SQL92/tag expression fails to parse in FilterAPI.buildSubscriptionData; or a consumer-group name that renders the retry topic (%RETRY%group) invalid.

Common situations: Consumer group names containing illegal characters (the retry topic is built from the group name, so an invalid group produces an invalid topic); subscribe() called before start() with a malformed expression like 'TagA || ' or non-ASCII tags; topics with spaces or special characters taken from dynamic configuration.

Related errors

• QUERY_NOT_FOUND
• Failed to load rocksdb for auth_acl, please check whether it
• lite subscription quota exceeded
• add subscription exception
• Can not find Message Queue for this topic, ${topic} Namesrv

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