apache/iceberg · error · RuntimeIOException

Failed to read stream while finding starting row position

Error message

Failed to read stream while finding starting row position

What it means

While scanning Avro blocks to locate the row position corresponding to a start offset, findStartingRowPos reads block metadata and rows from the stream. Any IOException other than EOF aborts the position search, and the method rethrows it as RuntimeIOException so callers fail fast instead of silently returning a wrong row offset.

Source

Thrown at core/src/main/java/org/apache/iceberg/avro/AvroIO.java:198

          if (!Arrays.equals(fileSync, blockSync)) {
            throw new RuntimeIOException("Invalid sync at %s", nextSyncPos);
          }
        }

        long rowCount = decoder.readLong();
        long compressedBlockSize = decoder.readLong();

        totalRows += rowCount;
        nextSyncPos = in.getPos() + compressedBlockSize;
      }

      return totalRows;

    } catch (EOFException e) {
      return totalRows;

    } catch (IOException e) {
      throw new RuntimeIOException(e, "Failed to read stream while finding starting row position");
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

Retry the scan/task — transient network IO failures usually resolve on retry with a fresh file handle
Verify the file is complete (compare with the manifest's recorded file size and checksum where available)
Re-open the file with a fresh InputFile instead of reusing the failed stream
If the file is genuinely truncated, rewrite the data file from a source of truth and repair the table

Defensive patterns

Strategy: retry

Validate before calling

// pre-check readability and size before scanning
if (!fileIO.exists(location)) throw new IllegalStateException("Missing file: " + location);
if (inputFile.getLength() != manifestEntryFileSize) throw new IllegalStateException("Truncated file: " + location);

Try / catch

try {
  return Avro.write(...) /* or read position */;
} catch (RuntimeIOException e) {
  if (isTransient(e)) return Retry.withBackoff(3).run(() -> findStartingRowPos(...));
  throw e;
}

Prevention

Configure object-store client retries and longer read timeouts for large files
Verify completed uploads (size/checksum) before committing manifests
Avoid reading over flaky networks without retry middleware
Keep file sizes moderate to reduce the window for mid-scan IO failures

When it happens

Trigger: Reading block metadata (rowCount, compressedBlockSize) or skipping rows in an Avro data file when the underlying stream raises a non-EOF IOException: network reset while reading from object storage, truncated file, closed stream, or local disk read failure.

Common situations: Transient S3/HDFS read errors during large scans; file truncated mid-upload; task retried after the local block cache was evicted; NFS/positioned reads failing on Hadoop FileIO mid-task.

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/01ceef4ea362a186. Report an issue: GitHub.