apache/beam · error · WontImplementError

sort_values(axis=index) is not supported because it imposes

Error message

sort_values(axis=index) is not supported because it imposes an ordering on the dataset which likely will not be preserved.

What it means

sort_values with axis=0/'index' orders the rows of the dataset — an ordering Beam's distributed, unordered PCollections cannot preserve — so the API raises WontImplementError. axis=1/'columns' is also rejected, but for a different reason: it would reorder columns based on the data (a non-deferred-column violation).

Source

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

              requires_partition_by=partitionings.Singleton(),
              preserves_partition_by=partitionings.Singleton()))

  @frame_base.args_to_kwargs(pd.DataFrame)
  @frame_base.populate_defaults(pd.DataFrame)
  def sort_values(self, axis, **kwargs):
    """``sort_values`` is not implemented.

    It is not implemented for ``axis=index`` because it imposes an ordering on
    the dataset, and it likely will not be maintained (see
    https://s.apache.org/dataframe-order-sensitive-operations).

    It is not implemented for ``axis=columns`` because it makes the order of
    the columns depend on the data (see
    https://s.apache.org/dataframe-non-deferred-columns)."""
    if axis in (0, 'index'):
      # axis=index imposes an ordering on the DataFrame rows which we do not
      # support
      raise frame_base.WontImplementError(
          "sort_values(axis=index) is not supported because it imposes an "
          "ordering on the dataset which likely will not be preserved.",
          reason="order-sensitive")
    else:
      # axis=columns will reorder the columns based on the data
      raise frame_base.WontImplementError(
          "sort_values(axis=columns) is not supported because the order of the "
          "columns in the result depends on the data.",
          reason="non-deferred-columns")

  @frame_base.with_docs_from(pd.DataFrame)
  @frame_base.args_to_kwargs(pd.DataFrame)
  @frame_base.populate_defaults(pd.DataFrame)
  @frame_base.maybe_inplace
  def sort_index(self, axis, **kwargs):
    """``axis=index`` is not allowed because it imposes an ordering on the
    dataset, and we cannot guarantee it will be maintained (see
    https://s.apache.org/dataframe-order-sensitive-operations). Only

View on GitHub (pinned to 12126d8942)

Solutions

1. Use df.nlargest(n, by) / df.nsmallest(n, by) if you only need top-k rows.
2. Use df.rank(...) or df.sort_index alternatives that are order-independent where possible.
3. Sort after collection: convert with to_pandas() and sort there (accepting a non-distributed stage).
4. If ordering only matters within groups, use groupby-based aggregations instead of a global sort.

Example fix

// before
df = df.sort_values('score', ascending=False)
// after
df = df.nlargest(10, 'score')  # or sort after to_pandas()

if kwargs.get('axis', 0) in (0, 'index'):
    raise ValueError('Global row sorting is unsupported in Beam; use nlargest/rank or sort after collection')

def sort_values_supported(axis=0) -> bool:
    return False  # both axis choices raise; route to alternatives

try:
    df = df.sort_values('score')
except frame_base.WontImplementError:
    df = df.nlargest(10, 'score')

When it happens

Trigger: df.sort_values(by='col') (axis defaults to 0/'index') or explicitly df.sort_values(by='col', axis=0); also df.sort_values(by=..., axis=1) hits the companion axis=columns error.

Common situations: Porting pandas reporting/Top-N code that relies on sorted output; preparing data for ordered display or rolling-window logic; rank-based feature engineering moved into Beam pipelines.

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

• fillna(method={method!r}, axis={axis!r}) is not supported be
• fillna(limit={method!r}, axis={axis!r}) is not supported bec
• Grouping by a concrete ndarray is order sensitive.
• replace(method={method!r}) is not supported because it is or
• align(method={method!r}) is not supported because it is orde

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