{"record":{"id":"320aeb40d6df7b16","repo":"apache/rocketmq","slug":"subscription-exception","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/DefaultMQPullConsumerImpl.java","lineNumber":829,"sourceCode":"        if (this.defaultMQPullConsumer.getConsumerTimeoutMillisWhenSuspend() < this.defaultMQPullConsumer.getBrokerSuspendMaxTimeMillis()) {\n            throw new MQClientException(\n                \"Long polling mode, the consumer consumerTimeoutMillisWhenSuspend must greater than brokerSuspendMaxTimeMillis\"\n                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),\n                null);\n        }\n    }\n\n    private void copySubscription() throws MQClientException {\n        try {\n            Set<String> registerTopics = this.defaultMQPullConsumer.getRegisterTopics();\n            if (registerTopics != null) {\n                for (final String topic : registerTopics) {\n                    SubscriptionData subscriptionData = FilterAPI.buildSubscriptionData(topic, SubscriptionData.SUB_ALL);\n                    this.rebalanceImpl.getSubscriptionInner().put(topic, subscriptionData);\n                }\n            }\n        } catch (Exception e) {\n            throw new MQClientException(\"subscription exception\", e);\n        }\n    }\n\n    public void updateConsumeOffset(MessageQueue mq, long offset) throws MQClientException {\n        this.isRunning();\n        this.offsetStore.updateOffset(mq, offset, false);\n    }\n\n    public MessageExt viewMessage(String topic, String msgId)\n        throws RemotingException, MQBrokerException, InterruptedException, MQClientException {\n        this.isRunning();\n        return this.mQClientFactory.getMQAdminImpl().viewMessage(topic, msgId);\n    }\n\n    public void registerFilterMessageHook(final FilterMessageHook hook) {\n        this.filterMessageHookList.add(hook);\n        log.info(\"register FilterMessageHook Hook, {}\", hook.hookName());\n    }","sourceCodeStart":811,"sourceCodeEnd":847,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPullConsumerImpl.java#L811-L847","documentation":"Thrown by copySubscription() during start() when building SubscriptionData for any of the registered topics (registerTopics) throws. Each topic is compiled through FilterAPI.buildSubscriptionData(topic, SUB_ALL); any failure — typically a malformed topic name — surfaces wrapped as 'subscription exception'.","triggerScenarios":"Calling setRegisterTopics(...) with a topic containing illegal characters or violating length limits before start(); a topic string with whitespace, empty string, or characters FilterAPI's TopicFilter rejects (valid pattern is ^[%|a-zA-Z0-9_-]+$ with length <= 127 in Validators).","commonSituations":"Topic names constructed from user input or environment variables without validation; trailing whitespace or newline in topic strings read from config files; topics exceeding the 127-char limit after concatenating prefixes.","solutions":["Inspect the cause chain — the wrapped exception names the offending topic and reason","Sanitize/validate topic names against Validators.topicValidator (regex ^[%|a-zA-Z0-9_-]+$) before registering them","Trim whitespace from topic strings sourced from config files or env vars"],"exampleFix":"// before\nconsumer.setRegisterTopics(Sets.newHashSet(\"order topic\", \"\")); // invalid\nconsumer.start();\n\n// after\nSet<String> topics = rawTopics.stream()\n    .map(String::trim)\n    .filter(t -> t.matches(\"[%|a-zA-Z0-9_-]+\"))\n    .collect(Collectors.toSet());\nconsumer.setRegisterTopics(topics);\nconsumer.start();","handlingStrategy":"validation","validationCode":"for (String t : topics) {\n    if (!t.trim().matches(\"[%|a-zA-Z0-9_-]+\") || t.length() > 127)\n        throw new IllegalArgumentException(\"invalid topic: \" + t);\n}","typeGuard":null,"tryCatchPattern":"catch (MQClientException e) { log.error(\"subscription failed, cause:\", e.getCause()); }","preventionTips":["Trim and validate topic names before setRegisterTopics","Reject empty or over-long topics at config load"],"tags":["rocketmq","pull-consumer","topic","subscription","validation"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}