apache/beam · error · WontImplementError

append() only accepts DeferredSeries instances, received

Error message

append() only accepts DeferredSeries instances, received {type(to_append)}

What it means

DeferredSeries.append only accepts another DeferredSeries as to_append. Passing anything else (a plain pandas Series, list, scalar, dict) fails with a WontImplementError naming the received type, because Beam cannot incorporate non-deferred data into the expression graph at that call site.

Solutions

Wrap the eager data as a DeferredSeries first (e.g. via the beam dataframe conversion API on a PCollection, or pd.concat at the eager level).
Convert to pandas and append eagerly if you're outside the pipeline anyway.
Use pd.concat([...]) with plain pandas objects instead of the Beam-specific append.

Example fix

// before
result = deferred_s.append([1, 2, 3])  # WontImplementError
// after
result = deferred_s.append(beam_df_from(list_series))  # or pd.concat after to_pandas()

Defensive patterns

Strategy: type-guard

Validate before calling

from apache_beam.dataframe.frames import DeferredSeries
if not isinstance(to_append, DeferredSeries):
    raise TypeError(f"append() requires DeferredSeries, got {type(to_append)}")

Type guard

def is_appendable(to_append):
    return isinstance(to_append, DeferredSeries)

Try / catch

from apache_beam.dataframe import frame_base
try:
    combined = s.append(to_append)
except frame_base.WontImplementError as e:
    if 'only accepts DeferredSeries' in str(e):
        combined = pd.concat([s.to_pandas(), pd.Series(to_append)])
    else:
        raise

Prevention

Convert eager pandas objects into deferred frames before appending.
Type-check to_append at the call site, not at pipeline runtime.
Prefer pd.concat([...]) which accepts both eager and deferred inputs.

When it happens

Trigger: Calling deferred_s.append(pandas_series), deferred_s.append([1, 2, 3]), or any non-DeferredSeries object, on pandas < 2.0 (on >= 2.0 the removal error fires first).

Common situations: Mixing eagerly loaded pandas data with deferred pipeline data; appending Python lists copied from pandas examples.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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

Appendix: source

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

    return self.index

  # Series.T == transpose. Both are a no-op
  T = frame_base._elementwise_method('T', base=pd.Series)
  transpose = frame_base._elementwise_method('transpose', base=pd.Series)
  shape = property(
      frame_base.wont_implement_method(
          pd.Series, 'shape', reason="non-deferred-result"))

  @frame_base.with_docs_from(pd.Series, removed_method=PD_VERSION >= (2, 0))
  @frame_base.args_to_kwargs(pd.Series, removed_method=PD_VERSION >= (2, 0))
  @frame_base.populate_defaults(pd.Series, removed_method=PD_VERSION >= (2, 0))
  def append(self, to_append, ignore_index, verify_integrity, **kwargs):
    """``ignore_index=True`` is not supported, because it requires generating an
    order-sensitive index."""
    if PD_VERSION >= (2, 0):
      raise frame_base.WontImplementError('append() was removed in Pandas 2.0.')
    if not isinstance(to_append, DeferredSeries):
      raise frame_base.WontImplementError(
          "append() only accepts DeferredSeries instances, received " +
          str(type(to_append)))
    if ignore_index:
      raise frame_base.WontImplementError(
          "append(ignore_index=True) is order sensitive because it requires "
          "generating a new index based on the order of the data.",
          reason="order-sensitive")

    if verify_integrity:
      # We can verify the index is non-unique within index partitioned data.
      requires = partitionings.Index()
    else:
      requires = partitionings.Arbitrary()

    return frame_base.DeferredFrame.wrap(
        expressions.ComputedExpression(
            'append', lambda s, to_append: s.append(
                to_append, verify_integrity=verify_integrity, **kwargs),

View on GitHub (pinned to 12126d8942)