Dataproc上PySpark classpath含依赖jar仍报ClassNotFoundException

即使SparkUI显示依赖Jar已加入ClassPath、通过--jars传参仍报错，通常是以下几类配置遗漏或错误导致，按优先级排查：

• Scala版本不匹配
  Dataproc各版本镜像绑定固定大版本的Scala环境：比如Dataproc 2.1+镜像默认搭载Scala 2.12，2.2+部分新版本搭载Scala 2.13，1.5.x旧版本搭载Scala 2.11。如果你的依赖Jar是基于其他Scala大版本编译的（比如Scala 2.13编译的Jar放到Scala 2.12环境），即使Jar文件在ClassPath路径下，也无法正常加载目标类。
  排查方式：在集群节点执行spark-submit --version查看当前环境绑定的Scala版本，核对所有依赖Jar的编译Scala版本完全匹配。
• Jar包本身内容错误或依赖缺失
  很多时候Jar在路径里不代表目标类真的存在：如果是自行打包的FatJar，检查shade插件配置是否错误排除了目标类、是否错误relocate了类路径、是否遗漏了SPI配置文件（META-INF/services目录下的实现声明）；如果是第三方依赖Jar，检查是否遗漏了该Jar对应的传递依赖。
  排查方式：把GCS上的Jar拉到本地，执行jar tf <你的jar文件名> | grep <报错的类全限定名>，确认目标类文件确实存在于Jar包内。
• Executor端类路径未生效
  SparkUI默认展示的是Driver进程的ClassPath，不代表所有Executor节点都成功加载了依赖：
  • 配置spark.jars时，需要同步配置spark.executor.extraClassPath参数，确保Executor进程能识别到依赖；
  • 如果集群内置了同包名的旧版本依赖，需要加--conf spark.executor.userClassPathFirst=true、--conf spark.driver.userClassPathFirst=true配置，强制JVM优先加载用户提供的Jar，避免类版本冲突导致加载失败。
• GCS权限问题导致Jar拉取静默失败
  如果Dataproc集群使用的服务账号没有存储Jar的GCS桶的storage.objects.get权限，可能出现Driver节点启动时成功拉取Jar（比如提交作业的本地节点有权限），但Worker节点拉取Jar时静默失败的情况——这类拉取失败通常只打WARN级日志，不会中断作业启动，直到实际调用目标类时才抛出ClassNotFoundException。
  排查方式：SSH到任意Worker节点，执行hadoop fs -ls gs://<你的Jar存储桶路径>/<依赖Jar文件名>，确认节点可以正常访问该文件。
• --jars参数格式错误
  通过gcloud命令行传--jars参数时，多个Jar路径之间必须用英文逗号分隔，不能加空格、不能给路径加多余引号，否则参数解析失败，Jar实际不会被加载到Executor端。正确的提交示例：

gcloud dataproc jobs submit pyspark main.py \
  --cluster=your-cluster \
  --region=your-region \
  --jars=gs://bucket/dep1.jar,gs://bucket/dep2.jar \
  --properties=spark.executor.userClassPathFirst=true,spark.driver.userClassPathFirst=true

快速验证技巧：作业启动后可以查看任意Executor的启动日志，确认依赖Jar是否被成功拉取到节点本地缓存目录，也可以直接进入本地缓存目录解压Jar，核对目标类是否存在。

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