使用Flink写入Iceberg表时出现org/apache/hadoop/conf/Configuration找不到错误

我有一个基础应用，尝试使用Flink将数据写入Iceberg表，核心代码如下：

StreamExecutionEnvironment env = StreamExecutionEnvironment.getExecutionEnvironment();
StreamTableEnvironment tenv = StreamTableEnvironment.create(env);
Configuration hadoopConf = new Configuration();
tenv.executeSql("CREATE CATALOG hive WITH ('type'='iceberg', 'catalog-type'='hive')");

执行运行命令：

flink run --detached --class org.example.App Test-1.0-SNAPSHOT.jar

出现报错：

java.lang.NoClassDefFoundError: org/apache/hadoop/conf/Configuration
        at org.apache.iceberg.flink.FlinkCatalogFactory.clusterHadoopConf(FlinkCatalogFactory.java:211)
        at org.apache.iceberg.flink.FlinkCatalogFactory.createCatalog(FlinkCatalogFactory.java:139)
        at org.apache.flink.table.factories.FactoryUtil.createCatalog(FactoryUtil.java:406)
        at org.apache.flink.table.api.internal.TableEnvironmentImpl.createCatalog(TableEnvironmentImpl.java:1356)
        at org.apache.flink.table.api.internal.TableEnvironmentImpl.executeInternal(TableEnvironmentImpl.java:1111)
        at org.apache.flink.table.api.internal.TableEnvironmentImpl.executeSql(TableEnvironmentImpl.java:701)
        at org.example.App.main(App.java:36)

已完成以下排查但问题依旧：

• 已配置HADOOP_CLASSPATH：HADOOP_CLASSPATH='/etc/hadoop/conf:/usr/lib/hadoop/lib/*:/usr/lib/hadoop/.//*:/usr/lib/hadoop-hdfs/./:/usr/lib/hadoop-hdfs/lib/*:/usr/lib/hadoop-hdfs/.//*:/usr/lib/hadoop-mapreduce/.//*:/usr/lib/hadoop-yarn/./:/usr/lib/hadoop-yarn/lib/*:/usr/lib/hadoop-yarn/.//*'，对应JAR包/usr/lib/hadoop/hadoop-common-3.1.2.jar存在；
• Maven依赖中已添加：

<dependency>
    <groupId>org.apache.hadoop</groupId>
    <artifactId>hadoop-common</artifactId>
    <version>3.1.2</version>
</dependency>

• 该依赖已打包进应用JAR，且能在归档文件中找到对应的.class文件；
• 代码中前一行已成功实例化Configuration类。

为何仍然出现找不到org/apache/hadoop/conf/Configuration的错误？

1. 核心原因：Flink类加载机制的隔离性 #

Iceberg的Flink Catalog Factory是在Flink的系统类加载上下文（而非应用的类加载上下文）中执行的，应用JAR中打包的Hadoop依赖无法被Flink的系统类加载器访问到，从而触发NoClassDefFoundError。

2. 可行解决步骤 #

方法一：将Hadoop依赖放入Flink集群的lib目录

将hadoop-common-3.1.2.jar及相关Hadoop依赖包复制到Flink集群的$FLINK_HOME/lib目录下，重启Flink集群。这样Flink的系统类加载器会直接加载这些依赖，避免类隔离问题。

方法二：提交任务时用--addclasspath显式指定依赖

在提交Flink任务时，通过--addclasspath参数强制让Flink的类加载器读取Hadoop依赖：

flink run --detached --class org.example.App --addclasspath /usr/lib/hadoop/hadoop-common-3.1.2.jar Test-1.0-SNAPSHOT.jar

若需要加载多个依赖，可批量指定：

flink run --detached --class org.example.App --addclasspath "/usr/lib/hadoop/*.jar:/usr/lib/hadoop/lib/*.jar" Test-1.0-SNAPSHOT.jar

方法三：调整Maven依赖的scope为provided（适合集群已部署Hadoop的场景）

如果Flink集群环境已预装对应版本的Hadoop，可将Maven依赖的scope设为provided，避免打包冲突，同时确保集群依赖版本与代码一致：

<dependency>
    <groupId>org.apache.hadoop</groupId>
    <artifactId>hadoop-common</artifactId>
    <version>3.1.2</version>
    <scope>provided</scope>
</dependency>

3. 验证要点 #

• 检查Flink集群lib目录下的Hadoop依赖版本是否与代码匹配；
• 通过Flink任务日志确认HADOOP_CLASSPATH环境变量已被正确读取；
• 确保Iceberg、Flink、Hadoop三者版本兼容（例如Iceberg 0.14+对应Flink 1.13+、Hadoop 3.x）。

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