apache/beam · error · WontImplementError

Using iloc to mutate a frame is not supported because it's…

Error message

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

What it means

iloc.__setitem__ unconditionally raises WontImplementError. Assigning through position-based indexing would need to know which physical row each element lands in, which is order-sensitive and cannot be deferred in Beam's distributed model.

Solutions

Use column-wise assignment instead: df['a'] = new_values (vectorized, order-independent).
Assign via .loc with explicit index labels if the index is well-defined.
Compute the new column with an expression and wrap it with df as a whole rather than mutating cells.
Do positional mutations in plain pandas outside the Beam pipeline.

Example fix

// before
df.iloc[:, 0] = df.iloc[:, 0] * 2

// after
df[df.columns[0]] = df[df.columns[0]] * 2

Defensive patterns

Strategy: validation

Validate before calling

if isinstance(indexer, type(df).iloc.__class__):
    raise ValueError("do not mutate via iloc in Beam dataframes")

Try / catch

try:
    df.iloc[:, 0] = values
except apachebeam.WontImplementError:
    df[df.columns[0]] = values

Prevention

Use column-wise assignment (df['col'] = ...) instead of cell-level mutations.
Treat Beam deferred frames as immutable; build new frames/expressions instead of in-place edits.
Reserve positional mutation for plain pandas pre/post processing.

When it happens

Trigger: Any assignment via the iloc indexer on a deferred Beam DataFrame, e.g. df.iloc[0, 'a'] = 5 or df.iloc[:, 0] = value.

Common situations: Translating pandas mutation code (setting a cell by position) into Beam; data-fixup scripts written for pandas; in-place edits during interactive exploration.

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

Appendix: source

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

        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(
        "Using iloc to mutate a frame is not supported because it's "
        "position-based indexing is sensitive to the order of the data.",
        reason="order-sensitive")


class _DeferredStringMethods(frame_base.DeferredBase):
  @frame_base.with_docs_from(pd.Series.str)
  @frame_base.args_to_kwargs(pd.Series.str)
  @frame_base.populate_defaults(pd.Series.str)
  def cat(self, others, join, **kwargs):
    """If defined, ``others`` must be a :class:`DeferredSeries` or a ``list`` of
    ``DeferredSeries``."""
    if others is None:
      # Concatenate series into a single String
      requires = partitionings.Singleton(reason=(
          "cat(others=None) concatenates all data in a Series into a single "
          "string, so it requires collecting all data on a single node."
      ))

View on GitHub (pinned to 12126d8942)