{"record":{"id":"5bfe1ee23dc496f4","repo":"alibaba/spring-ai-alibaba","slug":"failed-to-subscribe","errorCode":null,"errorMessage":"Failed to subscribe","messagePattern":"Failed to subscribe","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/base/mq/MqConsumerManager.java","lineNumber":100,"sourceCode":"\t\t\t\t\t\t\thandler.handle(mqMessage);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t\tcatch (Exception e) {\n\t\t\t\t\t\tlog.error(\"Failed to consume message, topic: {}, tag: {}\", messageView.getTopic(),\n\t\t\t\t\t\t\t\tmessageView.getTag(), e);\n\t\t\t\t\t\treturn ConsumeResult.FAILURE;\n\n\t\t\t\t\t}\n\t\t\t\t\treturn ConsumeResult.SUCCESS;\n\t\t\t\t})\n\t\t\t\t.build();\n\n\t\t\tconsumerMap.put(group, consumer);\n\t\t\tlog.info(\"Subscribed to group: {}, topic: {}\", group, topic);\n\t\t}\n\t\tcatch (ClientException e) {\n\t\t\tlog.error(\"Failed to subscribe to group: {}\", group, e);\n\t\t\tthrow new RuntimeException(\"Failed to subscribe\", e);\n\t\t}\n\t}\n\n\t/**\n\t * Shutdown all consumers gracefully\n\t */\n\t@PreDestroy\n\tpublic void shutdown() {\n\t\tconsumerMap.forEach((group, consumer) -> {\n\t\t\ttry {\n\t\t\t\tconsumer.close();\n\t\t\t}\n\t\t\tcatch (IOException e) {\n\t\t\t\tlog.error(\"Failed to close consumer, group: {}\", group, e);\n\t\t\t}\n\n\t\t\tlog.info(\"Consumer shutdown successfully, group: {}\", group);\n\t\t});","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/base/mq/MqConsumerManager.java#L82-L118","documentation":"MqConsumerManager.subscribe catches rocketmq ClientException when creating/registering a consumer and rethrows it as RuntimeException('Failed to subscribe', e). This happens when the RocketMQ 5.x client SDK fails to build or start the push consumer for the given group/topic — typically broker/connection problems, invalid endpoints, or conflicting consumer groups. Startup of the MQ-backed feature aborts with this error.","triggerScenarios":"Calling MqConsumerManager.subscribe(group, ...) where the RocketMQ ClientException occurs: unreachable or wrong nameserver/endpoint, invalid access credentials, consumer group already taken or not authorized, topic does not exist, or network blocked between admin server and broker.","commonSituations":"RocketMQ endpoint misconfigured in application config (wrong host/port); broker behind a firewall or in another VPC; missing/wrong AK/SK credentials; topic not pre-created on the broker; duplicate subscription of the same group from another running instance.","solutions":["Read the wrapped ClientException cause in the log for the exact SDK failure reason","Verify RocketMQ endpoint/nameserver, credentials, and topic configuration in application config","Check network reachability (telnet/curl) from the admin server host to the broker endpoint","Confirm the topic exists and the consumer group is authorized; stop conflicting instances using the same group","Fix config, then restart the application so subscribe() runs again"],"exampleFix":"// before (config)\nrocketmq.endpoint=127.0.0.1:6600   // unreachable broker\n// after\nrocketmq.endpoint=mq-broker.internal:8081  // reachable, credentials set\n","handlingStrategy":"retry","validationCode":"// validate config before calling subscribe\nassert rocketMqEndpoint != null && rocketMqEndpoint.contains(\":\") : \"invalid rocketmq endpoint\";\n// optionally probe reachability\ntry (var s = new Socket()) { s.connect(new InetSocketAddress(host, port), 3000); }","typeGuard":null,"tryCatchPattern":"try {\n    mqConsumerManager.subscribe(group, topic, handler);\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().equals(\"Failed to subscribe\")) {\n        // inspect e.getCause() (ClientException); backoff and retry, then alert if it persists\n    } else {\n        throw e;\n    }\n}","preventionTips":["Pre-create the topic and authorize the consumer group on the broker before startup","Verify RocketMQ endpoint, credentials, and network reachability from the deployment environment","Avoid running multiple instances sharing the same consumer group unintentionally","Retry subscribe with exponential backoff to tolerate transient broker unavailability"],"tags":["rocketmq","mq","subscribe","network"],"backgroundTag":"mq-subscribe-failed","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}