Spark-Kafka集成问题：spark-submit提交时出现ClassNotFound错误

1. 严格匹配Spark与Kafka连接器版本 #

Spark的Kafka连接器版本必须和你的Spark主版本完全对应，举几个常用版本对应关系：

• Spark 3.3.x → org.apache.spark:spark-sql-kafka-0-10_2.12:3.3.0
• Spark 3.2.x → org.apache.spark:spark-sql-kafka-0-10_2.12:3.2.4
• Spark 3.1.x → org.apache.spark:spark-sql-kafka-0-10_2.12:3.1.3

版本不匹配是引发类找不到错误的最常见原因，不要混用跨版本的连接器。

2. 用spark-submit参数正确引入依赖 #

别手动拷贝jar包，优先用--packages让Spark自动拉取并管理所有依赖（包括kafka-clients、commons-pool2等传递依赖）：

spark-submit --packages org.apache.spark:spark-sql-kafka-0-10_2.12:3.3.0 your_kafka_parquet_script.py

如果是离线环境，需要提前下载完整依赖包，再用--jars参数全量指定：

spark-submit --jars spark-sql-kafka-0-10_2.12-3.3.0.jar,kafka-clients-2.8.1.jar,commons-pool2-2.11.1.jar your_kafka_parquet_script.py

注意：必须包含所有依赖jar，只加spark-sql-kafka的jar会因为缺少依赖类报错。

3. 检查SparkSession配置 #

不要在代码中错误覆盖连接器相关配置，比如不要乱设spark.sql.streaming.source.providerClass。如果要在代码中指定依赖，写法如下（但更推荐在spark-submit参数中设置，避免环境耦合）：

from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .appName("KafkaToParquet") \
    .config("spark.jars.packages", "org.apache.spark:spark-sql-kafka-0-10_2.12:3.3.0") \
    .getOrCreate()

# 读取Kafka数据
df = spark.readStream \
    .format("kafka") \
    .option("kafka.bootstrap.servers", "your_broker:9092") \
    .option("subscribe", "your_topic") \
    .load()

# 处理并写入Parquet
query = df.writeStream \
    .format("parquet") \
    .option("path", "/path/to/parquet") \
    .option("checkpointLocation", "/path/to/checkpoint") \
    .start()

query.awaitTermination()

4. 集群模式下确保依赖全节点可达 #

如果在YARN/K8s集群运行：

• YARN集群用--deploy-mode cluster时，--packages会自动把依赖分发到所有节点；用--jars的话，要确保jar包在HDFS路径或所有节点本地相同路径下。
• 检查集群Spark配置，避免spark.driver.extraClassPath和spark.executor.extraClassPath出现冲突覆盖。

5. 验证依赖加载情况 #

添加--verbose参数提交，查看Spark加载的依赖列表，确认kafka相关jar是否被正确加载：

spark-submit --verbose --packages org.apache.spark:spark-sql-kafka-0-10_2.12:3.3.0 your_kafka_parquet_script.py

内容的提问来源于stack exchange，提问作者It'sMeSreehari