apache/beam · error · RuntimeError

Trying to iterate through a cleared ListBuffer.

Error message

Trying to iterate through a cleared ListBuffer.

What it means

ListBuffer.__iter__ raises RuntimeError if the buffer has been cleared. Iterating a cleared buffer would yield nothing but usually indicates a lifecycle bug (data was already released), so it fails fast instead of silently returning empty results.

Solutions

1. Copy the buffer contents (list(buffer)) before calling clear().
2. Iterate before clearing; reorder code so consumption precedes cleanup.
3. Call reset() if the buffer was intentionally cleared for reuse and should be repopulated first.

Example fix

# before
items = list(buf)  # after buf.clear() -> RuntimeError
# after
items = list(buf)
buf.clear()

if not buffer.cleared:
    items = list(buffer)

def is_readable(buf):
    return not buf.cleared

try:
    items = list(buffer)
except RuntimeError:
    items = []  # buffer was already cleared

When it happens

Trigger: Iterating (for x in buffer, list(buffer), etc.) a ListBuffer after clear() was called — e.g. reading buffered elements after bundle teardown or from a stale reference.

Common situations: Holding a reference to a buffer across clear() and reading it later; runner code consuming buffers in a different order than clear/partition; debugging code inspecting buffers post-clear.

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

• Grouping table append after read.
• ListBuffer append after read.
• Trying to append to a cleared ListBuffer.
• Trying to partition a cleared ListBuffer.
• Trying to reset a non-cleared ListBuffer.

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

Appendix: source

Thrown at sdks/python/apache_beam/runners/portability/fn_api_runner/execution.py:170

    else:
      if not self._grouped_output:
        output_stream_list = [create_OutputStream() for _ in range(n)]
        idx = 0
        for input in self._inputs:
          input_stream = create_InputStream(input)
          while input_stream.size() > 0:
            decoded_value = self._coder_impl.decode_from_stream(
                input_stream, True)
            self._coder_impl.encode_to_stream(
                decoded_value, output_stream_list[idx], True)
            idx = (idx + 1) % n
        self._grouped_output = [[output_stream.get()]
                                for output_stream in output_stream_list]
      return self._grouped_output

  def __iter__(self) -> Iterator[bytes]:
    if self.cleared:
      raise RuntimeError('Trying to iterate through a cleared ListBuffer.')
    return iter(self._inputs)

  def clear(self) -> None:
    self.cleared = True
    self._inputs = []
    self._grouped_output = None

  def reset(self) -> None:
    """Resets a cleared buffer for reuse."""
    if not self.cleared:
      raise RuntimeError('Trying to reset a non-cleared ListBuffer.')
    self.cleared = False


class GroupingBuffer(object):
  """Used to accumulate groupded (shuffled) results."""
  def __init__(
      self,

View on GitHub (pinned to 12126d8942)