{"record":{"id":"cb6c54c1508c9dc1","repo":"apache/iceberg","slug":"failed-to-load-iceberg-table-from-table-loader-cb6c54","errorCode":null,"errorMessage":"Failed to load iceberg table from table loader: ${tableLoader}","messagePattern":"Failed to load iceberg table from table loader: (.+?)","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":null,"severity":"error","filePath":"flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/sink/IcebergSink.java","lineNumber":919,"sourceCode":"  }\n\n  private static String defaultSuffix(String uidSuffix, String defaultSuffix) {\n    if (uidSuffix == null || uidSuffix.isEmpty()) {\n      return defaultSuffix;\n    }\n    return uidSuffix;\n  }\n\n  private static SerializableTable checkAndGetTable(TableLoader tableLoader, Table table) {\n    if (table == null) {\n      if (!tableLoader.isOpen()) {\n        tableLoader.open();\n      }\n\n      try (TableLoader loader = tableLoader) {\n        return (SerializableTable) SerializableTable.copyOf(loader.loadTable());\n      } catch (IOException e) {\n        throw new UncheckedIOException(\n            \"Failed to load iceberg table from table loader: \" + tableLoader, e);\n      }\n    }\n\n    return (SerializableTable) SerializableTable.copyOf(table);\n  }\n\n  /**\n   * Clean up after removing {@link Builder#tableSchema}\n   *\n   * @deprecated since 1.10.0, will be removed in 2.0.0. Use {@link #toFlinkRowType(Schema,\n   *     ResolvedSchema)} instead.\n   */\n  @Deprecated\n  private static RowType toFlinkRowType(Schema schema, TableSchema requestedSchema) {\n    if (requestedSchema != null) {\n      // Convert the flink schema to iceberg schema firstly, then reassign ids to match the existing\n      // iceberg schema.","sourceCodeStart":901,"sourceCodeEnd":937,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/sink/IcebergSink.java#L901-L937","documentation":"IcebergSink's Builder builds the sink by loading the Table via the supplied TableLoader and wrapping it as a SerializableTable. If loadTable() throws IOException — missing/unreadable metadata, unreachable filesystem, or bad credentials — it is rethrown as this UncheckedIOException naming the loader. This happens eagerly at builder time (unlike error 1505, which occurs at operator init).","triggerScenarios":"Calling IcebergSink.builder().tableLoader(loader)...append() where loader.open()/loadTable() raises IOException: wrong metadata location, table dropped/renamed, TaskManager/client lacking Hadoop or cloud credentials, network partition to HDFS/S3.","commonSituations":"Pointing the loader at a path that no longer exists after table recreation; submitting jobs from an environment without core-site/hive-site conf; expired S3 tokens; catalog URI misconfiguration in Flink SQL or DataStream API code.","solutions":["Confirm the TableLoader points to an existing table (verify via the catalog before building the sink).","Ensure Hadoop/cloud configuration and credentials are on the classpath and valid in the submission environment.","Fix the metadata location/warehouse path in the loader configuration.","If the table was recreated, rebuild the sink with a fresh loader rather than reusing a stale one."],"exampleFix":"// before\nTableLoader loader = TableLoader.fromCatalog(CatalogLoader.hadoop(\"hcat\", conf, \"file:/bad/path\"), TableIdentifier.of(\"db\", \"t\"));\n// after\nTableLoader loader = TableLoader.fromCatalog(CatalogLoader.hadoop(\"hcat\", conf, warehousePath), TableIdentifier.of(\"db\", \"t\"));","handlingStrategy":"try-catch","validationCode":"try (TableLoader loader = tableLoader) {\n  loader.open();\n  Table t = loader.loadTable();\n  Preconditions.checkArgument(t != null, \"Table must load before building IcebergSink\");\n}","typeGuard":null,"tryCatchPattern":"try { buildIcebergSink(); } catch (UncheckedIOException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Failed to load iceberg table\")) {\n    LOG.error(\"TableLoader could not load the table; check catalog config and metadata location\", e);\n  }\n}","preventionTips":["Pre-flight: load the table once at submission time and fail fast with a clear message.","Confirm the metadata location exists and credentials are valid before building the sink.","Rebuild the sink with a fresh TableLoader after table drop/recreate operations."],"tags":["flink","iceberg","table-loader","io","sink"],"backgroundTag":"file-read-failed","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}