{"record":{"id":"0ccea8196b15f768","repo":"apache/rocketmq","slug":"subscription-exception-0ccea8","errorCode":null,"errorMessage":"subscription exception","messagePattern":"subscription exception","errorType":"exception","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java","lineNumber":1240,"sourceCode":"            }\n\n            if (null == this.messageListenerInner) {\n                this.messageListenerInner = this.defaultMQPushConsumer.getMessageListener();\n            }\n\n            switch (this.defaultMQPushConsumer.getMessageModel()) {\n                case BROADCASTING:\n                    break;\n                case CLUSTERING:\n                    final String retryTopic = MixAll.getRetryTopic(this.defaultMQPushConsumer.getConsumerGroup());\n                    SubscriptionData subscriptionData = FilterAPI.buildSubscriptionData(retryTopic, SubscriptionData.SUB_ALL);\n                    this.rebalanceImpl.getSubscriptionInner().put(retryTopic, subscriptionData);\n                    break;\n                default:\n                    break;\n            }\n        } catch (Exception e) {\n            throw new MQClientException(\"subscription exception\", e);\n        }\n    }\n\n    public MessageListener getMessageListenerInner() {\n        return messageListenerInner;\n    }\n\n    private void updateTopicSubscribeInfoWhenSubscriptionChanged() {\n        if (doNotUpdateTopicSubscribeInfoWhenSubscriptionChanged) {\n            return;\n        }\n        Map<String, SubscriptionData> subTable = this.getSubscriptionInner();\n        if (subTable != null) {\n            for (final Map.Entry<String, SubscriptionData> entry : subTable.entrySet()) {\n                final String topic = entry.getKey();\n                this.mQClientFactory.updateTopicRouteInfoFromNameServer(topic);\n            }\n        }","sourceCodeStart":1222,"sourceCodeEnd":1258,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java#L1222-L1258","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the cause (e.getCause()) of the MQClientException — it names the exact invalid topic or expression","Validate topic names against ^[%|a-zA-Z0-9_-]+$ and subscription expressions before calling subscribe()","Sanitize the consumer group name: it is embedded in %RETRY%<group> and must form a legal topic name","Ensure the subscription string is either '*' or a well-formed 'TagA || TagB' expression"],"exampleFix":"// before\nconsumer.subscribe(\"order topic\", \"TagA ||\"); // trailing operator: parse fails inside start()\n// after\nconsumer.subscribe(\"orderTopic\", \"TagA || TagB\");\n// and pre-validate:\n// TopicValidator.validateTopic(topic); FilterAPI.buildSubscriptionData(topic, expr); // dry-run parse","handlingStrategy":"try-catch","validationCode":"TopicValidator.validateTopic(topic);\nFilterAPI.buildSubscriptionData(topic, expr); // dry-run parse before start()\nif (!consumer.getMessageModel().name().matches(\"BROADCASTING|CLUSTERING\")) throw new IllegalArgumentException(\"bad model\");","typeGuard":null,"tryCatchPattern":"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 */ }","preventionTips":["Sanitize consumer group names: they become %RETRY%<group> topics","Validate every topic/subscription pair with FilterAPI before subscribe()/start()","Log the cause chain — the wrapper message is generic"],"tags":["rocketmq","consumer","subscription","startup","wrapped-exception"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}