apache/beam · error · WontImplementError

align(copy=False) is not supported because it might be an…

Error message

align(copy=False) is not supported because it might be an inplace operation depending on the data. Please prefer the default align(copy=True).

What it means

DeferredFrame.align(copy=False) is rejected because in pandas copy=False may or may not be an inplace operation depending on the data (whether indexes already match), introducing data-dependent behavior. Beam's dataframe API requires the default copy=True and raises WontImplementError otherwise.

Solutions

Remove copy=False and use the default align(other) (copy=True)
If avoiding copies mattered, restructure to join/merge or reindex explicitly where copy semantics are clear

Example fix

// before
l, r = left.align(right, copy=False)
// after
l, r = left.align(right)

Defensive patterns

Strategy: validation

Validate before calling

assert kwargs.get('copy', True) is True, 'align(copy=False) unsupported on deferred frames'

Type guard

def beam_safe_align_kwargs(kwargs):
    return kwargs.get('copy', True)

Try / catch

from apache_beam.dataframe import frame_base
try:
    l, r = left.align(right)
except frame_base.WontImplementError:
    l, r = left.align(right)  # drop copy=False

Prevention

Do not port pandas copy=False micro-optimizations into Beam dataframe code
Rely on the deferred API's copy semantics instead of in-place tricks
Audit shared pandas/Beam helper functions for copy=False arguments

When it happens

Trigger: Calling align(other, copy=False) on any DeferredDataFrame/Series, typically as a micro-optimization ported from pandas code.

Common situations: Copying pandas performance tweaks (copy=False to avoid copies) into Beam pipelines; code sharing an align helper between pandas and Beam dataframes.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

    else:
      raise NotImplementedError(key)

  @frame_base.with_docs_from(pd.DataFrame)
  @frame_base.args_to_kwargs(pd.DataFrame)
  @frame_base.populate_defaults(pd.DataFrame)
  def align(self, other, join, axis, copy, level, method, **kwargs):
    """Aligning per level is not yet supported. Only the default,
    ``level=None``, is allowed.

    Filling NaN values via ``method`` is not supported, because it is
    `order-sensitive
    <https://s.apache.org/dataframe-order-sensitive-operations>`_. Only the
    default, ``method=None``, is allowed.

    ``copy=False`` is not supported because its behavior (whether or not it is
    an inplace operation) depends on the data."""
    if not copy:
      raise frame_base.WontImplementError(
          "align(copy=False) is not supported because it might be an inplace "
          "operation depending on the data. Please prefer the default "
          "align(copy=True).")
    if method is not None and method != lib.no_default:
      raise frame_base.WontImplementError(
          f"align(method={method!r}) is not supported because it is "
          "order sensitive. Only align(method=None) is supported.",
          reason="order-sensitive")
    if kwargs:
      raise NotImplementedError('align(%s)' % ', '.join(kwargs.keys()))

    # In Pandas 2.0, all aggregations lost the level keyword.
    if PD_VERSION < (2, 0) and level is not None:
      # Could probably get by partitioning on the used levels.
      requires_partition_by = partitionings.Singleton(reason=(
          f"align(level={level}) is not currently parallelizable. Only "
          "align(level=None) can be parallelized."))
    elif axis in ('columns', 1):

View on GitHub (pinned to 12126d8942)