alibaba/spring-ai-alibaba · error · RuntimeException
Failed to subscribe
Error message
Failed to subscribe
What it means
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.
Source
Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/base/mq/MqConsumerManager.java:100
handler.handle(mqMessage);
}
}
catch (Exception e) {
log.error("Failed to consume message, topic: {}, tag: {}", messageView.getTopic(),
messageView.getTag(), e);
return ConsumeResult.FAILURE;
}
return ConsumeResult.SUCCESS;
})
.build();
consumerMap.put(group, consumer);
log.info("Subscribed to group: {}, topic: {}", group, topic);
}
catch (ClientException e) {
log.error("Failed to subscribe to group: {}", group, e);
throw new RuntimeException("Failed to subscribe", e);
}
}
/**
* Shutdown all consumers gracefully
*/
@PreDestroy
public void shutdown() {
consumerMap.forEach((group, consumer) -> {
try {
consumer.close();
}
catch (IOException e) {
log.error("Failed to close consumer, group: {}", group, e);
}
log.info("Consumer shutdown successfully, group: {}", group);
});View on GitHub (pinned to f82da0b50f)
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
Example fix
// before (config) rocketmq.endpoint=127.0.0.1:6600 // unreachable broker // after rocketmq.endpoint=mq-broker.internal:8081 // reachable, credentials set
Defensive patterns
Strategy: retry
Validate before calling
// validate config before calling subscribe
assert rocketMqEndpoint != null && rocketMqEndpoint.contains(":") : "invalid rocketmq endpoint";
// optionally probe reachability
try (var s = new Socket()) { s.connect(new InetSocketAddress(host, port), 3000); } Try / catch
try {
mqConsumerManager.subscribe(group, topic, handler);
} catch (RuntimeException e) {
if (e.getMessage() != null && e.getMessage().equals("Failed to subscribe")) {
// inspect e.getCause() (ClientException); backoff and retry, then alert if it persists
} else {
throw e;
}
} Prevention
- 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
When it happens
Trigger: 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.
Common situations: 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.
Related errors
AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09).
Data as JSON: /api/errors/5bfe1ee23dc496f4.
Report an issue: GitHub.