What causes "Cannot call read after iterating." in apache/beam?

Choose one access mode: iterate fully or use read()/readline() consistently.

apache/beam · error · NotImplementedError

Cannot call read after iterating.

Error message

Cannot call read after iterating.

What it means

The file-like wrapper around splittable reads permits either sequential reads or iteration, but not both; calling read() after iteration has begun raises NotImplementedError because the buffer position semantics cannot be guaranteed.

Source

Thrown at sdks/python/apache_beam/dataframe/io.py:552

    line_start = 0
    chunk = self._read()
    while True:
      line_end = chunk.find(self._splitter._delim, line_start)
      while line_end == -1:
        more = self._read()
        if not more:
          if line_start < len(chunk):
            yield chunk[line_start:]
          return
        chunk = chunk[line_start:] + more
        line_start = 0
        line_end = chunk.find(self._splitter._delim, line_start)
      yield chunk[line_start:line_end + 1]
      line_start = line_end + 1

  def read(self, size=-1):
    if self._iterator:
      raise NotImplementedError('Cannot call read after iterating.')
    return self._read(size)

  def _read(self, size=-1):
    if self._header:
      res = self._header
      self._header = None
      return res
    elif self._done:
      return self._empty
    elif size == -1:
      self._buffer += self._underlying.read()
    elif not self._buffer:
      self._buffer = self._underlying.read(size)

    if not self._buffer:
      self._tracker.try_claim(self._tracker.current_restriction().stop)
      self._done = True
      return self._empty

View on GitHub (pinned to 12126d8942)

Solutions

Choose one access mode: iterate fully or use read()/readline() consistently.
Re-open the file object if you need to restart reading from the beginning.
Use _read/readline API surface only, avoiding iteration, when mixing is required.

Example fix

// before
for line in f:
    break
data = f.read(1024)  # raises
// after
data = f.read(1024)
for line in io.StringIO(data.decode()):
    ...

Defensive patterns

Strategy: try-catch

Try / catch

try:
    data = handle.read(size)
except NotImplementedError:
    handle = reopen()  # fresh file object for read-after-iterate
    data = handle.read(size)

Prevention

Pick one access mode per file handle: read OR iterate
Re-open handles instead of mixing modes
Wrap file-like handles before passing to third-party parsers that iterate

When it happens

Trigger: Mixing access modes on the handle returned by the source, e.g. iterating the file object (for line in f) and then calling f.read(size), or a library helper that reads a header then falls back to .read().

Common situations: Custom code that peeks via iteration then reads the remainder; third-party parsing utilities assuming full file-like semantics.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/f9d859e615234fb4. Report an issue: GitHub.