SpringBoot 项目整合 RocketMQ 启动失败的常见错误总结

SpringBoot 项目整合 RocketMQ 启动失败的常见错误总结 | 极客日志

SpringBoot 项目整合 RocketMQ 启动失败的常见错误总结

一、日志框架配置问题

1. RocketMQ 日志框架未正确配置

报错内容：

RocketMQLog:WARN No appenders could be found for logger (io.netty.util.internal.InternalThreadLocalMap). RocketMQLog:WARN Please initialize the logger system properly.

原因： RocketMQ 默认使用自己的日志框架，未与 SpringBoot 的 Slf4j 集成。

解决方案：在启动类中添加：

System.setProperty("rocketmq.client.logUseSlf4j", "true");

并在配置文件中添加：

logging:
  level:
    RocketmqClient: ERROR
    io: netty: ERROR

二、版本兼容性问题

1. SpringBoot 版本过低

报错内容：

Caused by: java.lang.ClassNotFoundException: org.apache.rocketmq.client

原因： SpringBoot 1.x 版本与 RocketMQ 2.0.4 不兼容。

解决方案：将 SpringBoot 版本升级到 2.1.0.RELEASE 或更高版本。

2. RocketMQ 与 SpringBoot 版本不匹配

报错内容：

The following dependencies have a problem: - rocketmq-spring-boot-starter: 2.0.4 - spring-boot-starter: 1.5.9.RELEASE

原因： RocketMQ 客户端与 SpringBoot 版本不兼容。

解决方案：检查并确保使用的 RocketMQ 版本与 SpringBoot 版本兼容（参考官方文档推荐组合）。

三、依赖冲突问题

1. 依赖冲突导致启动失败

报错内容：

Caused by: java.lang.NoClassDefFoundError: org/apache/rocketmq/client/producer/DefaultMQProducer

原因：依赖库之间存在版本冲突。

解决方案：

使用 mvn dependency:tree 检查依赖树
在 pom.xml 中明确指定版本：

<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-spring-boot-starter</artifactId>
    <version>2.0.4</version>
    <!-- 排除冲突的依赖 -->
    <exclusions>
        <exclusion>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
        </exclusion>
    </exclusions>
</dependency>

四、自动装配配置缺失

1. RocketMQTemplate 无法自动注入

报错内容：

Field rocketMQTemplate in com.sks.crm.service.RocketMQProducerService required a bean of type 'org.apache.rocketmq.spring.core.RocketMQTemplate' that could not be found.

原因： SpringBoot 3.0+ 已废弃 spring.factories 自动装配机制。

解决方案：在 resources 下创建 META-INF 文件夹，然后在 META-INF 下创建 org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件，并添加：

org.apache.rocketmq.spring.autoconfigure.RocketMQAutoConfiguration

五、RocketMQ 服务配置问题

1. NameServer 地址配置错误

报错内容：

org.apache.rocketmq.client.exception.MQClientException: No route info of topic: test-topic, please make sure you have created the topic first.

原因： RocketMQ 配置的 NameServer 地址不正确。

解决方案：检查配置文件中 rocketmq.name-server 是否正确，确保 NameServer 已启动且可访问。

2. 磁盘空间不足

报错内容：

org.apache.rocketmq.client.exception.MQBrokerException: CODE: 14 DESC: service not available now. It may be caused by one of the following reasons: the broker's disk is full [CL:0.92 CQ:0.92 INDEX:0.92], messages are put to the slave, message store has been shut down, etc. BROKER:169.254.87.77:10911

原因： RocketMQ Broker 所在服务器磁盘空间不足。

解决方案：

清理磁盘空间
修改 runbroker.cmd 文件，增加：

set "JAVA_OPT=%JAVA_OPT% -server -Xms512m -Xmx512m -Xmn128m -Drocketmq.broker.diskSpaceWarningLevelRatio=0.99"

六、消费者组配置问题

1. 消费者组已存在

报错内容：

Caused by: org.apache.rocketmq.client.exception.MQClientException: The consumer group[my-consumer] has been created before, specify another name please

原因：同一个消费者组名已在 RocketMQ 中创建，重复使用。

解决方案：确保每个消费者组名是唯一的，不要重复使用。

七、配置文件格式问题

1. 配置文件格式错误

报错内容：

Caused by: org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'rocketMQTemplate' defined in class path resource [org/apache/rocketmq/spring/autoconfigure/RocketMQAutoConfiguration.class]: Instantiation of bean failed; nested exception is org.springframework.beans.BeanInstantiationException: Failed to instantiate [org.apache.rocketmq.spring.core.RocketMQTemplate]: Constructor threw exception; nested exception is java.lang.IllegalArgumentException: rocketmq.name-server is required.

原因：配置文件中缺少必要的 RocketMQ 配置项。

解决方案：确保配置文件包含必要的 RocketMQ 配置：

rocketmq:
  name-server: 127.0.0.1:9876
  producer:
    group: my-group
  consumer:
    group: my-consumer

八、ACL 认证配置问题

1. ACL 认证配置缺失

报错内容：

org.apache.rocketmq.client.exception.MQClientException: Access denied, the topic 'test-topic' is not allowed to be accessed by the client

原因： RocketMQ 开启 ACL 认证，但客户端未配置 AccessKey 和 SecretKey。

解决方案：在配置文件中添加：

rocketmq:
  producer:
    access-key: AK
    secret-key: SK

或在消费者注解中指定：

@RocketMQMessageListener(topic = "test-topic", consumerGroup = "my-consumer", accessKey = "AK", secretKey = "SK")

SpringBoot 项目整合 RocketMQ 启动失败的常见错误总结