apache/beam · error · WontImplementError

Indexing a series with key of type

Error message

Indexing a series with key of type {type(key)} is not supported because it produces a non-deferred result.

What it means

DeferredSeries.__getitem__ falls through to this error for any key type that is not a slice, callable, DeferredSeries, or accepted scalar — e.g. tuples, dicts, lists of labels. Such a key would produce a single concrete (non-deferred) value or an unrepresentable result, which Beam's deferred model refuses by design (reason "non-deferred-result"). Beam prefers a clear error over returning a surprising deferred scalar.

Solutions

  1. Check the key type before indexing; use slices, callables (e.g. s[lambda x: ...]), or DeferredSeries keys.
  2. For list-of-labels selection, build a boolean DeferredSeries mask or use a supported selection method.
  3. Extract concrete values only after to_pandas().

Example fix

// before
s[[0, 1, 2]]  # list key -> non-deferred result
// after
s[s.index.isin([0, 1, 2], level=None)] if supported, or s[s > threshold]  # deferred mask
Defensive patterns

Strategy: type-guard

Validate before calling

ALLOWED = (slice,)
if not (isinstance(key, ALLOWED) or callable(key) or isinstance(key, DeferredSeries)):
    raise TypeError(f"unsupported deferred indexing key type: {type(key)}")

Type guard

def is_indexable_key(key):
    return isinstance(key, slice) or callable(key) or isinstance(key, DeferredSeries)

Try / catch

from apache_beam.dataframe import frame_base
try:
    out = s[key]
except frame_base.WontImplementError as e:
    if 'non-deferred result' in str(e):
        out = s.to_pandas()[key]
    else:
        raise

Prevention

When it happens

Trigger: s[(1, 2)], s[{'a': 1}], s[[0, 1, 2]] (non-boolean list), or any custom key object on a DeferredSeries.

Common situations: MultiIndex-style tuple keys on deferred series; list-of-labels selection copied from pandas; accidental passing of a wrong-typed variable as the key.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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

Appendix: source

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

      return frame_base.DeferredFrame.wrap(
          expressions.ComputedExpression(
              # yapf: disable
              'getitem',
              lambda df, indexer: df[indexer],
              [self._expr, key._expr],
              requires_partition_by=partitionings.Index(),
              preserves_partition_by=partitionings.Arbitrary()))

    elif pd.core.series.is_iterator(key) or pd.core.common.is_bool_indexer(key):
      raise frame_base.WontImplementError(
          "Accessing a DeferredSeries with an iterator is sensitive to the "
          "order of the data.",
          reason="order-sensitive")

    else:
      # We could consider returning a deferred scalar, but that might
      # be more surprising than a clear error.
      raise frame_base.WontImplementError(
          f"Indexing a series with key of type {type(key)} is not supported "
          "because it produces a non-deferred result.",
          reason="non-deferred-result")

  @frame_base.with_docs_from(pd.Series)
  def keys(self):
    return self.index

  # Series.T == transpose. Both are a no-op
  T = frame_base._elementwise_method('T', base=pd.Series)
  transpose = frame_base._elementwise_method('transpose', base=pd.Series)
  shape = property(
      frame_base.wont_implement_method(
          pd.Series, 'shape', reason="non-deferred-result"))

  @frame_base.with_docs_from(pd.Series, removed_method=PD_VERSION >= (2, 0))
  @frame_base.args_to_kwargs(pd.Series, removed_method=PD_VERSION >= (2, 0))
  @frame_base.populate_defaults(pd.Series, removed_method=PD_VERSION >= (2, 0))

View on GitHub (pinned to 12126d8942)