apache/beam · error · WontImplementError

mode(axis=columns) is not supported because it produces a…

Error message

mode(axis=columns) is not supported because it produces a variable number of columns depending on the data.

What it means

apache_beam.dataframe raises WontImplementError for DataFrame.mode(axis=1/'columns') because row-wise mode can yield a variable number of winning values per row, so the output column count cannot be known lazily before the data is inspected. Beam's deferred dataframe API requires a statically-known schema (deferred columns). A parallelizable implementation is tracked in Beam issue 20946.

Solutions

Use axis=0 (default) mode, which is supported, if column-wise mode fits the problem.
Compute row-wise mode manually with apply/row-wise expressions that return a fixed schema, or pad results to a fixed width.
Fall back to a non-distributed pandas computation if the data fits in memory (collect via to_pandas).
Track Beam issue 20946 for a future parallelizable implementation.

Example fix

// before
modes = df.mode(axis='columns')
// after
modes = df.mode()  # axis=0, per-column mode

Defensive patterns

Strategy: validation

Validate before calling

def check_mode_axis(axis):
    if axis in (1, 'columns'):
        raise ValueError("Beam DataFrames do not support mode(axis='columns')")

Type guard

def mode_supported(axis) -> bool:
    return axis not in (1, 'columns')

Try / catch

from apache_beam.dataframe import frame_base
try:
    modes = df.mode(axis='columns')
except frame_base.WontImplementError:
    modes = df.mode()

Prevention

Remember Beam DataFrames need statically-known schemas: avoid operations that produce variable column counts.
Prefer axis=0 aggregations in Beam pipelines.
Check the Beam pandas API docs' supported/unsupported matrix before porting.

When it happens

Trigger: Calling df.mode() with axis=1 or axis='columns' on a Beam DeferredDataFrame.

Common situations: Porting pandas code that computes per-row most-frequent values directly to Beam pipelines; users unaware Beam requires static column schemas.

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

Appendix: source

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

            requires_partition_by=partitionings.Arbitrary(),
            preserves_partition_by=partitionings.Arbitrary(),
            proxy=proxy))

  __matmul__ = dot

  @frame_base.with_docs_from(pd.DataFrame)
  def mode(self, axis=0, *args, **kwargs):
    """mode with axis="columns" is not implemented because it produces
    non-deferred columns.

    mode with axis="index" is not currently parallelizable. An approximate,
    parallelizable implementation of mode may be added in the future
    (`Issue 20946 <https://github.com/apache/beam/issues/20946>`_)."""

    if axis == 1 or axis == 'columns':
      # Number of columns is max(number mode values for each row), so we can't
      # determine how many there will be before looking at the data.
      raise frame_base.WontImplementError(
          "mode(axis=columns) is not supported because it produces a variable "
          "number of columns depending on the data.",
          reason="non-deferred-columns")
    return frame_base.DeferredFrame.wrap(
        expressions.ComputedExpression(
            'mode',
            lambda df: df.mode(*args, **kwargs),
            [self._expr],
            #TODO(https://github.com/apache/beam/issues/20946):
            # Can we add an approximate implementation?
            requires_partition_by=partitionings.Singleton(reason=(
                "mode(axis='index') cannot currently be parallelized. See "
                "https://github.com/apache/beam/issues/20946 tracking the "
                "possble addition of an approximate, parallelizable "
                "implementation of mode."
            )),
            preserves_partition_by=partitionings.Singleton()))

View on GitHub (pinned to 12126d8942)