apache/iceberg · error · UncheckedIOException

Failed to load iceberg table from table loader:

Error message

Failed to load iceberg table from table loader: 

What it means

FlinkSink's operator chain loads the Iceberg Table via the provided TableLoader during operator initialization (open/setup). If loadTable() throws an IOException — e.g. the table metadata file is missing, unreadable, or the underlying filesystem/object store is unreachable — it is wrapped in this UncheckedIOException naming the TableLoader.

Source

Thrown at flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/sink/FlinkSink.java:444

    }

    private DataStreamSink<Void> chainIcebergOperators() {
      Preconditions.checkArgument(
          inputCreator != null,
          "Please use forRowData() or forMapperOutputType() to initialize the input DataStream.");
      Preconditions.checkNotNull(tableLoader, "Table loader shouldn't be null");

      DataStream<RowData> rowDataInput = inputCreator.apply(uidPrefix);

      if (table == null) {
        if (!tableLoader.isOpen()) {
          tableLoader.open();
        }

        try (TableLoader loader = tableLoader) {
          this.table = loader.loadTable();
        } catch (IOException e) {
          throw new UncheckedIOException(
              "Failed to load iceberg table from table loader: " + tableLoader, e);
        }
      }

      flinkWriteConf = new FlinkWriteConf(table, writeOptions, readableConfig);

      // Find out the equality field id list based on the user-provided equality field column names.
      Set<Integer> equalityFieldIds =
          SinkUtil.checkAndGetEqualityFieldIds(table, equalityFieldColumns);

      RowType flinkRowType =
          resolvedSchema != null
              ? toFlinkRowType(table.schema(), resolvedSchema)
              : toFlinkRowType(table.schema(), tableSchema);
      int writerParallelism =
          flinkWriteConf.writeParallelism() == null
              ? rowDataInput.getParallelism()
              : flinkWriteConf.writeParallelism();

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the catalog and TableLoader configuration (warehouse path, Hadoop conf, credentials) is available on all TaskManagers, not just the client.
2. Confirm the table exists and its metadata location is valid via the catalog (SHOW/inspect metadata pointer).
3. Check filesystem/object-store reachability and credential validity from the cluster.
4. Recreate the sink after the table has been recreated/renamed so the loader points to live metadata.

Example fix

// before
TableLoader loader = TableLoader.fromHadoopTable("hdfs://nn/warehouse/db/table"); // cluster cannot resolve nn
// after
TableLoader loader = TableLoader.fromCatalog(CatalogLoader.hive("hive_catalog", hiveConf, uri, db, table));

try (TableLoader loader = tableLoader) {
  loader.open();
  Table t = loader.loadTable(); // fail fast on client before submitting job
}

try { loader.loadTable(); } catch (IOException e) {
  throw new UncheckedIOException("Pre-flight table load failed for " + loader, e);
}

When it happens

Trigger: TableLoader.open()/loadTable() raising IOException because the metadata JSON or manifest files can't be read: wrong warehouse/Hadoop conf in the cluster, deleted or renamed table, expired cloud credentials, or a catalog that points to nonexistent metadata.

Common situations: Submitting the Flink job from a machine with valid conf but the TaskManagers lack Hadoop/AWS configuration; the table was dropped/rewritten while the job was being built; version-hive/.hadoop catalog misconfiguration; S3 credentials expiring at task startup.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Failed to load iceberg table from table loader: ${tableLoade
• Failed to load iceberg table from table loader: ${tableLoade
• Failed to load iceberg table from table loader: ${tableLoade
• Failed to create tableMaintenance
• Failed to list partitions of table %s

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/c650cbf5d06020a4. Report an issue: GitHub.