KafkaTemplate配置失败：新项目正常旧项目报错求助

核心报错原因 #

报错链的根因是java.lang.ClassNotFoundException: org.apache.kafka.clients.consumer.ConsumerGroupMetadata，这个类属于Apache Kafka客户端库（kafka-clients），出现问题的本质是工作项目中Kafka客户端与Spring Kafka的版本不兼容，或缺失了正确版本的kafka-clients依赖。

ConsumerGroupMetadata类是在kafka-clients 2.6.0版本中新增的，若工作项目引入的kafka-clients版本低于2.6.0，而使用的Spring Kafka版本依赖该类（比如Spring Kafka 2.7+版本），就会触发该报错。

具体解决步骤 #

1. 对齐Spring Boot与Kafka生态版本 #

Spring Boot父依赖会统一管理Spring Kafka和kafka-clients的兼容版本，不要手动指定不匹配的版本：

• Spring Boot 2.7.x → Spring Kafka 2.8.x + kafka-clients 3.0.x
• Spring Boot 2.6.x → Spring Kafka 2.7.x + kafka-clients 2.8.x
• Spring Boot 2.5.x → Spring Kafka 2.6.x + kafka-clients 2.6.x

检查工作项目的pom.xml（Maven）或build.gradle（Gradle），确保没有手动覆盖kafka-clients版本，让Spring Boot父依赖自动管理版本。

2. 确认kafka-clients依赖存在 #

确保项目依赖中包含kafka-clients，无需手动指定版本，由Spring Boot统一管理：

• Maven依赖配置：

<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-clients</artifactId>
</dependency>

• Gradle依赖配置：

implementation 'org.apache.kafka:kafka-clients'

3. 排查依赖冲突 #

执行命令查看kafka-clients的实际引入版本，确认是否存在版本冲突：

• Maven：mvn dependency:tree | grep kafka-clients
• Gradle：./gradlew dependencies | grep kafka-clients

如果输出多个版本，说明存在依赖冲突，需在引入旧版本kafka-clients的第三方依赖中排除该依赖，示例（Maven）：

<dependency>
    <groupId>第三方依赖groupId</groupId>
    <artifactId>第三方依赖artifactId</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.apache.kafka</groupId>
            <artifactId>kafka-clients</artifactId>
        </exclusion>
    </exclusions>
</dependency>

4. 验证重试主题配置兼容性 #

你使用的RetryTopicConfiguration是Spring Kafka的重试主题功能，该功能对Kafka客户端版本有明确要求，确保版本匹配后，重试配置才能正常初始化。

内容的提问来源于stack exchange，提问作者Garam Choi