What causes "Failed to create iceberg input splits for table: " in apache/iceberg?

Verify table name/path resolves and FileIO credentials are configured (e.g. s3.access-key, hadoop conf)

apache/iceberg · error · UncheckedIOException

Failed to create iceberg input splits for table:

Error message

Failed to create iceberg input splits for table:

What it means

FlinkSource.build uses format.createInputSplits(0) to estimate split count for auto parallelism; any IOException while creating those splits is wrapped in UncheckedIOException naming the table. This means the underlying Iceberg scan/file IO failed (usually filesystem access, snapshot resolution, or manifest reading) during source construction.

Source

Thrown at flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/source/FlinkSource.java:295

    public DataStream<RowData> build() {
      Preconditions.checkNotNull(env, "StreamExecutionEnvironment should not be null");
      FlinkInputFormat format = buildFormat();

      ScanContext context = contextBuilder.build();
      TypeInformation<RowData> typeInfo =
          FlinkCompatibilityUtil.toTypeInfo(FlinkSchemaUtil.convert(context.project()));

      if (!context.isStreaming()) {
        int parallelism =
            SourceUtil.inferParallelism(
                readableConfig,
                context.limit(),
                () -> {
                  try {
                    return format.createInputSplits(0).length;
                  } catch (IOException e) {
                    throw new UncheckedIOException(
                        "Failed to create iceberg input splits for table: " + table, e);
                  }
                });
        if (env.getMaxParallelism() > 0) {
          parallelism = Math.min(parallelism, env.getMaxParallelism());
        }
        return env.createInput(format, typeInfo).setParallelism(parallelism);
      } else {
        StreamingMonitorFunction function = new StreamingMonitorFunction(tableLoader, context);

        String monitorFunctionName = String.format("Iceberg table (%s) monitor", table);
        String readerOperatorName = String.format("Iceberg table (%s) reader", table);

        return env.addSource(function, monitorFunctionName)
            .transform(readerOperatorName, typeInfo, StreamingReaderOperator.factory(format));
      }
    }
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

Verify table name/path resolves and FileIO credentials are configured (e.g. s3.access-key, hadoop conf)
Check the referenced snapshot still exists (not expired); set a valid snapshot-id or refresh the table
Test reading the table outside Flink (Spark/iceberg inspect) to isolate Flink config issues
Inspect the chained IOException cause for the actual IO failure (permissions, DNS, timeout)

Example fix

// before
FlinkSource.forRowData().env(env).tableLoader(loader).build();
// after: validate table is readable before building
Table table = loader.loadTable();
table.refresh();
table.currentSnapshot(); // throws if metadata unreadable
FlinkSource.forRowData().env(env).tableLoader(loader).build();

Defensive patterns

Strategy: try-catch

Validate before calling

Table t = tableLoader.loadTable();
t.refresh();
Preconditions.checkState(t.currentSnapshot() != null, "Table has no readable snapshot");

Try / catch

try {
  source = FlinkSource.forRowData().env(env).tableLoader(loader).build();
} catch (UncheckedIOException e) {
  throw new RuntimeException("Cannot read table " + e.getCause().getMessage(), e);
}

Prevention

Validate FileIO credentials and table path before submitting the job
Pin snapshot-id if expiration jobs run concurrently
Confirm table readability with a small scan outside Flink first

When it happens

Trigger: Calling FlinkSource.forRowData().project(...).build() where the table's FileIO cannot read metadata/manifests, the table location is wrong or credentials are missing, or the snapshot referenced no longer exists.

Common situations: Misconfigured S3/HDFS credentials or endpoint, table path typo, snapshot expired between planning and build, network outage to object store, read permission denied on metadata files.

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

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