apache/beam · error · WontImplementError

Using iloc to select rows is not supported because it's…

Error message

Using iloc to select rows is not supported because it's position-based indexing is sensitive to the order of the data.

What it means

The __getitem__ of the iloc-based row indexer raises WontImplementError when a row selection other than a full slice (:,) is requested. Position-based (integer-location) indexing depends on the physical order of rows, which Beam does not guarantee during distributed execution, so it is order-sensitive and unsupported.

Solutions

  1. Use label-based indexing via .loc instead of .iloc when an index exists.
  2. For 'first N rows', use a supported alternative like a global window + combiner, or restructure to avoid position semantics.
  3. If order matters, sort explicitly and use techniques compatible with Beam (e.g. partition by index stored as a column).
  4. Perform the position-based selection in plain pandas before/after the Beam pipeline.

Example fix

// before
subset = df.iloc[2:10, ['a']]

// after
subset = df.loc[df.index[2:10], ['a']]  # requires meaningful index
Defensive patterns

Strategy: type-guard

Validate before calling

rows = idx[0] if isinstance(idx, tuple) else idx
if not (rows == slice(None)):
    raise ValueError("iloc row selection is unsupported in Beam; use .loc")

Type guard

def beam_safe_iloc_index(idx):
    rows = idx[0] if isinstance(idx, tuple) else idx
    return rows == slice(None, None, None)

Try / catch

try:
    subset = df.iloc[2:10, ['a']]
except apachebeam.WontImplementError:
    subset = df.loc[df.index[2:10], ['a']]

Prevention

When it happens

Trigger: df.iloc[5], df.iloc[2:10], df.iloc[[0, 3]] or any row selection that is not slice(None) on a deferred Beam DataFrame, e.g. df.iloc[rows, ['col']].

Common situations: Porting pandas code that grabs rows by position (first N rows, specific row numbers) to Beam; assuming distributed rows keep their original order; using iloc for head/tail-like operations.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/dataframe/frames.py:4987

            requires_partition_by=(
                partitionings.JoinIndex()
                if len(args) > 1
                else partitionings.Arbitrary()),
            preserves_partition_by=partitionings.Arbitrary()))

  __setitem__ = frame_base.not_implemented_method(
      'loc.setitem', base_type=pd.core.indexing._LocIndexer)

@populate_not_implemented(pd.core.indexing._iLocIndexer)
class _DeferredILoc(object):
  def __init__(self, frame):
    self._frame = frame

  def __getitem__(self, index):
    if isinstance(index, tuple):
      rows, _ = index
      if rows != slice(None, None, None):
        raise frame_base.WontImplementError(
            "Using iloc to select rows is not supported because it's "
            "position-based indexing is sensitive to the order of the data.",
            reason="order-sensitive")
      return frame_base.DeferredFrame.wrap(
          expressions.ComputedExpression(
              'iloc',
              lambda df: df.iloc[index],
              [self._frame._expr],
              requires_partition_by=partitionings.Arbitrary(),
              preserves_partition_by=partitionings.Arbitrary()))
    else:
      raise frame_base.WontImplementError(
          "Using iloc to select rows is not supported because it's "
          "position-based indexing is sensitive to the order of the data.",
          reason="order-sensitive")

  def __setitem__(self, index, value):
    raise frame_base.WontImplementError(

View on GitHub (pinned to 12126d8942)