apache/iceberg · error · RuntimeIOException

Failed to read next record

Error message

Failed to read next record

What it means

AvroRangeIterator.next() advances the underlying Avro reader and deserializes the next record into the reuse instance. An IOException during deserialization or stream read is wrapped in RuntimeIOException with a stable 'Failed to read next record' message, since a partial record cannot be returned.

Source

Thrown at core/src/main/java/org/apache/iceberg/avro/AvroIterable.java:162

    }

    @Override
    public D next() {
      if (!hasNext()) {
        throw new NoSuchElementException();
      }
      return reader.next();
    }

    @Override
    public D next(D reuse) {
      if (!hasNext()) {
        throw new NoSuchElementException();
      }
      try {
        return reader.next(reuse);
      } catch (IOException e) {
        throw new RuntimeIOException(e, "Failed to read next record");
      }
    }

    @Override
    public void sync(long position) throws IOException {
      reader.sync(position);
    }

    @Override
    public boolean pastSync(long position) throws IOException {
      return reader.pastSync(position);
    }

    @Override
    public long tell() throws IOException {
      return reader.tell();
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Retry the read with a fresh file handle to rule out transient IO
2. Verify the compression codec libraries are present (snappy/zstd/bzip2)
3. Confirm the reader function/schema matches the file's schema (check getMetadata for writer schema)
4. If corruption is confirmed, restore/rewrite the affected data file

try (CloseableIterator<D> iter = iterable.iterator()) {
  while (iter.hasNext()) sink(iter.next());
} catch (RuntimeIOException e) {
  if (attempts++ < maxRetries) reopenAndSkip(consumedRows);
  else throw e;
}

When it happens

Trigger: Calling next() on a range iterator when block decompression fails, the stream ends mid-block, or the record schema cannot decode the bytes (schema/codec mismatch between writer and reader).

Common situations: Corrupted object in storage; reader schema incompatible with file schema causing decode errors surfaced as IOExceptions; missing decompression codec; network interruption mid-block.

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

• Cannot read manifest list file: %s
• Failed to create snapshot list writer for path: %s
• Cannot read manifest list file: %s
• Failed to close manifest reader
• Failed to create manifest writer for path: %s

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