Spark场景调用API报TCLIService$Iface类找不到异常排查

java.lang.ClassNotFoundException: org.apache.hive.service.cli.thrift.TCLIService$Iface 是典型的类加载缺失错误，缺失的类属于Hive Thrift RPC服务的核心接口类，结合给出的环境信息，常见触发原因有三类：

• 类路径配置缺失：贴出的Spark Master启动命令中，classpath仅加载了Spark自身jars目录下的包，如果使用的是未内置Hive依赖的Spark官方预编译包，启动ThriftServer或对接Hive元数据的API服务时，JVM无法扫描到hive-service相关依赖包，调用表查询接口时就会抛出该错误。
• 服务定位错误：当前贴出的是Spark Master节点的日志路径，但Spark Master默认监听8080端口、Thriftserver WebUI默认监听4040端口，二者都不会直接监听8082提供/hive/default/tables接口，看到的异常很可能不是Spark Master抛出的，是监听8082端口的其他服务（比如独立部署的Spark SQL网关、Hive REST代理服务）抛出的，存在找错日志对应进程的问题。
• 依赖版本冲突：如果监听8082端口的服务引入的hive-service依赖版本，和启动的ThriftServer实际使用的Hive版本不兼容，也会出现类找不到、类版本不匹配的错误。

• 先定位真正抛出异常的进程：执行命令 ss -nltp | grep 8082 拿到监听8082端口的进程ID，再通过ps aux | grep 进程ID查看该进程的启动命令、classpath配置、日志路径，不要错看Spark Master的日志。
• 验证ThriftServer本身可用性：不要仅通过4040页面判断服务正常，直接用beeline客户端连接验证：执行beeline -u jdbc:hive2://localhost:10000 -n $(whoami)，连接成功后执行show databases、show tables，如果命令能正常返回结果，说明ThriftServer本身依赖完整、服务可用，问题出在8082端口的调用方服务。
• 检查报错进程的依赖：在报错进程的classpath对应目录下执行find . -name "hive-service-*.jar"，确认是否存在对应jar包；如果存在，解压jar包看内部是否包含org/apache/hive/service/cli/thrift/TCLIService$Iface.class文件，同时核对jar包版本和ThriftServer加载的Hive版本是否一致。
• 检查是否存在类加载隔离配置：如果报错进程是Spark提交的作业，检查是否配置了类加载优先级策略，导致用户jar和Spark内置jar互相隔离，无法加载到Hive相关类。

• 如果是8082端口的服务缺失依赖：将和ThriftServer同版本的hive-service-*.jar、hive-service-rpc-*.jar、libthrift-*.jar拷贝到该服务的lib依赖目录，重启服务即可。
• 如果是Spark/ThriftServer本身缺失Hive依赖：替换为官方预编译的带Hive支持的Spark发行包，或者启动ThriftServer时通过--jars参数指定上述缺失的Hive依赖包路径，将依赖加入classpath。
• 如果是版本冲突：统一Spark、ThriftServer、8082端口API服务三者引用的Hive依赖版本，排查依赖树排除掉重复引入的不兼容版本Hive包。
• 如果是类加载隔离导致依赖无法识别：在Spark配置中添加spark.driver.userClassPathFirst=true、spark.executor.userClassPathFirst=true，将用户引入的Hive依赖加载优先级调高，避免被Spark内置的低优先级类加载器拦截。

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