升级Kafka Streams版本后出现java.lang.NoClassDefFoundError的排查咨询

可能的原因 #

• 依赖版本冲突：虽然应用基于同一模板，但出问题的两个应用可能引入了额外依赖，间接拉取了与Kafka Streams 3.6.1不兼容的RocksDB版本（比如旧版rocksdbjni），导致类初始化时出现冲突。
• JNI本地库加载失败：RocksDB依赖系统本地库（如Linux的.so、Windows的.dll），异常应用的运行环境可能存在以下问题：
  • 操作系统架构不匹配（比如Kafka自带的是x86_64库，却运行在ARM架构机器上）
  • 本地库文件损坏或缺失
  • 运行用户无权限读取本地库文件
  • JVM参数限制了本地库加载路径
• 构建打包差异：两个异常应用的构建配置可能存在细微差别，比如打包时排除了RocksDB的类或本地库，或者使用的打包工具（如ShadowJar）未正确包含RocksDB的本地资源。
• 状态目录异常：应用的Kafka Streams状态目录中存在损坏的RocksDB文件，或目录权限不足，导致初始化DBOptions时触发底层错误，进而抛出类初始化异常。

排查步骤 #

1. 检查依赖树

   • 针对异常应用，执行依赖分析命令：
     • Maven：mvn dependency:tree | grep rocksdb
     • Gradle：./gradlew dependencies | grep rocksdb
   • 确认rocksdbjni版本与Kafka Streams 3.6.1依赖的版本一致（Kafka 3.6.1对应RocksDB 7.10.2）。若存在冲突版本，在构建配置中排除旧版依赖。

2. 排查JNI库加载问题

   • 添加JVM启动参数-verbose:jni，启动应用后查看日志中JNI库加载的详细信息，确认是否有“找不到库”“架构不匹配”等错误。
   • 显式指定本地库路径：添加JVM参数-Djava.library.path=<path-to-rocksdb-native-libs>，路径指向Kafka依赖的rocksdbjni包中的本地库目录（如Maven仓库中rocksdbjni-7.10.2-linux64.jar解压后的META-INF/native目录），测试是否能正常启动。
   • 对比正常与异常应用的运行环境：检查OS版本、CPU架构、JVM版本是否完全一致，排除环境差异导致的库加载失败。

3. 验证构建打包结果

   • 解压异常应用的JAR包，检查是否包含org/rocksdb/DBOptions.class文件，以及META-INF/native目录下是否存在对应系统的本地库文件。
   • 对比正常与异常应用的构建脚本（如pom.xml/build.gradle），重点查看依赖排除、打包插件配置（如ShadowJar的include/exclude规则），确认是否存在差异导致RocksDB资源未被正确打包。

4. 检查状态目录

   • 停止异常应用，备份状态目录后将其删除，重新启动应用，观察是否能正常初始化。若恢复正常，说明原状态目录存在损坏文件。
   • 检查状态目录的权限，确保运行应用的用户拥有读写该目录的权限。

5. 排查类加载顺序

   • 添加JVM启动参数-verbose:class，启动后查看org.rocksdb.DBOptions类的加载来源，确认其来自正确的rocksdbjni JAR包，而非其他冲突依赖。

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