apache/beam · error · WontImplementError

value_counts(sort=True) is not supported because it imposes…

Error message

value_counts(sort=True) is not supported because it imposes an ordering on the dataset which likely will not be preserved.

What it means

DeferredSeries.value_counts(sort=True) (pandas' default) sorts counts descending, imposing a global ordering that a distributed pipeline cannot preserve deterministically. The Beam dataframe API rejects sort=True with WontImplementError (reason 'order-sensitive'); only sort=False is allowed.

Solutions

Pass sort=False: series.value_counts(sort=False)
Sort explicitly afterwards with sort_values() if a deferred sort is acceptable at that point
Compute top-K via a different mechanism (e.g. nlargest on the counts series with keep='all')

Example fix

// before
counts = s.value_counts()
// after
counts = s.value_counts(sort=False)

Defensive patterns

Strategy: validation

Validate before calling

counts = s.value_counts(sort=False)  # sort=True is unsupported on DeferredSeries

Type guard

def beam_safe_value_counts(kwargs):
    return not kwargs.get('sort', True)

Try / catch

from apache_beam.dataframe import frame_base
try:
    counts = s.value_counts(sort=False)
except frame_base.WontImplementError:
    counts = s.value_counts(sort=False)

Prevention

Never call value_counts() without sort=False on deferred frames
If sorted output is required, sort explicitly afterwards via sort_values()
Add code review checks for pandas default arguments in Beam ports

When it happens

Trigger: Calling series.value_counts() with default arguments (sort defaults to True in pandas) or explicitly value_counts(sort=True); also value_counts with bins relies on a non-parallelizable path.

Common situations: Porting pandas value_counts() calls verbatim; building frequency tables expecting sorted output; using the result to pick top-K categories.

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

Appendix: source

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

  @frame_base.with_docs_from(pd.Series)
  def value_counts(
      self,
      sort=False,
      normalize=False,
      ascending=False,
      bins=None,
      dropna=True):
    """``sort`` is ``False`` by default, and ``sort=True`` is not supported
    because it imposes an ordering on the dataset which likely will not be
    preserved.

    When ``bin`` is specified this operation is not parallelizable. See
    [Issue 20903](https://github.com/apache/beam/issues/20903) tracking the
    possible addition of a distributed implementation."""

    if sort:
      raise frame_base.WontImplementError(
          "value_counts(sort=True) is not supported because it imposes an "
          "ordering on the dataset which likely will not be preserved.",
          reason="order-sensitive")

    if bins is not None:
      return frame_base.DeferredFrame.wrap(
          expressions.ComputedExpression(
              'value_counts',
              lambda s: s.value_counts(
                  normalize=normalize, bins=bins, dropna=dropna)[self._expr],
              requires_partition_by=partitionings.Singleton(
                  reason=(
                      "value_counts with bin specified requires collecting "
                      "the entire dataset to identify the range.")),
              preserves_partition_by=partitionings.Singleton(),
          ))

    if dropna:

View on GitHub (pinned to 12126d8942)