apache/beam · error · ValueError

align_axis must be one of ('index', 0, 'columns', 1). got {a

Error message

align_axis must be one of ('index', 0, 'columns', 1). got {align_axis!r}.

What it means

DeferredSeries.compare accepts an align_axis parameter that must be one of 'index', 0, 'columns', or 1, mirroring pandas. The Beam implementation dispatches partitioning behavior on this value; anything else means it cannot be mapped, so a ValueError is raised naming the allowed values.

Source

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

          reason="order-sensitive")
    else:
      raise TypeError(
          "repeat(repeats=) value must be an int or a "
          f"DeferredSeries (encountered {type(repeats)}).")

  if hasattr(pd.Series, 'compare'):

    @frame_base.with_docs_from(pd.Series)
    @frame_base.args_to_kwargs(pd.Series)
    @frame_base.populate_defaults(pd.Series)
    def compare(self, other, align_axis, **kwargs):

      if align_axis in ('index', 0):
        preserves_partition = partitionings.Singleton()
      elif align_axis in ('columns', 1):
        preserves_partition = partitionings.Arbitrary()
      else:
        raise ValueError(
            "align_axis must be one of ('index', 0, 'columns', 1). "
            f"got {align_axis!r}.")

      return frame_base.DeferredFrame.wrap(
          expressions.ComputedExpression(
              'compare',
              lambda s, other: s.compare(other, align_axis, **kwargs),
              [self._expr, other._expr],
              requires_partition_by=partitionings.Index(),
              preserves_partition_by=preserves_partition))


@populate_not_implemented(pd.DataFrame)
@frame_base.DeferredFrame._register_for(pd.DataFrame)
class DeferredDataFrame(DeferredDataFrameOrSeries):
  def __repr__(self):
    return (
        f'DeferredDataFrame(columns={list(self.columns)}, '

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass align_axis='index' (or 0) to stack differences vertically.
2. Pass align_axis='columns' (or 1) to keep the original column layout.
3. Fix casing/whitespace: 'Index' or 'index ' is invalid; print repr(align_axis) to debug.
4. Guard the value before calling: if align_axis not in ('index', 0, 'columns', 1): raise/normalize.

Example fix

// before
df1.compare(df2, align_axis='rows')  # invalid
// after
df1.compare(df2, align_axis='columns')

VALID = ('index', 0, 'columns', 1)
if align_axis not in VALID:
    raise ValueError(f'align_axis must be one of {VALID}')

def is_valid_align_axis(v) -> bool:
    return v in ('index', 0, 'columns', 1)

try:
    diff = s1.compare(s2, align_axis=align_axis)
except ValueError:
    diff = s1.compare(s2, align_axis='columns')

When it happens

Trigger: Calling s1.compare(s2, align_axis='Index') (wrong case), align_axis=2, align_axis=None, or any value outside {'index', 0, 'columns', 1}.

Common situations: Porting pandas compare() calls where align_axis was read from config or computed dynamically; typos like 'rows'/'cols' instead of the pandas-legal values.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• op must be one of ('idxmax', 'idxmin'). got {op!r}.
• Cannot specify both 'labels' and 'index'/'columns'
• axis must be one of (0, 1, 'index', 'columns'), got '%s'
• groupby(as_index=False)
• You have to supply one of 'by' and 'level'

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