apache/beam · error · NotImplementedError

When axis= , only n and/or weights may be specified. frac…

Error message

When axis={axis!r}, only n and/or weights may be specified. frac, random_state, and replace=True are not yet supported (got frac={frac!r}, random_state={random_state!r}, replace={replace!r}). See https://github.com/apache/beam/issues/21010.

What it means

DeferredFrame.sample() with axis='index' only supports sampling by count (n) and/or weights. Passing frac, random_state, or replace=True is not implemented because per-partition sampling semantics cannot be replicated; Beam throws NotImplementedError and points to GitHub issue 21010.

Solutions

  1. Use only n and/or weights arguments (omit frac, random_state, replace)
  2. Compute the count yourself and pass n=int(len(df)*frac) after materializing
  3. Materialize with to_pandas() and use pandas sample for full argument support

Example fix

// before
sampled = df.beam.sample(frac=0.1, random_state=42)
// after
sampled = df.beam.sample(n=int(len(df) * 0.1))  # or use to_pandas().sample(...)
Defensive patterns

Strategy: validation

Validate before calling

if frac is not None or random_state is not None or replace:
    raise ValueError('beam sample(axis=index) supports only n and/or weights')

Try / catch

try:
    sampled = dframe.sample(n=n)
except NotImplementedError:
    sampled = dframe.to_pandas().sample(frac=frac, random_state=seed, replace=replace)

Prevention

When it happens

Trigger: Calling df.sample(frac=0.5) or df.sample(n=..., replace=True, random_state=42) on a Beam deferred DataFrame with axis='index' (the default)

Common situations: Converting pandas sampling/bootstrap code to Beam; attempting reproducible sampling with a fixed random_state

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

Appendix: source

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

    Note that pandas will raise an error if ``n`` is larger than the length
    of the dataset, while the Beam DataFrame API will simply return the full
    dataset in that case.

    sample is fully supported for axis='columns'."""
    if axis in (1, 'columns'):
      # Sampling on axis=columns just means projecting random columns
      # Eagerly generate proxy to determine the set of columns at construction
      # time
      proxy = self._expr.proxy().sample(n=n, frac=frac, replace=replace,
                                        weights=weights,
                                        random_state=random_state, axis=axis)
      # Then do the projection
      return self[list(proxy.columns)]

    # axis='index'
    if frac is not None or random_state is not None or replace:
      raise NotImplementedError(
          f"When axis={axis!r}, only n and/or weights may be specified. "
          "frac, random_state, and replace=True are not yet supported "
          f"(got frac={frac!r}, random_state={random_state!r}, "
          f"replace={replace!r}). See "
          "https://github.com/apache/beam/issues/21010.")

    if n is None:
      n = 1

    if isinstance(weights, str):
      weights = self[weights]

    tmp_weight_column_name = "___Beam_DataFrame_weights___"

    if weights is None:
      self_with_randomized_weights = frame_base.DeferredFrame.wrap(
          expressions.ComputedExpression(
          'randomized_weights',

View on GitHub (pinned to 12126d8942)