apache/beam · error · TransformError

Expecting a PCollection argument.

Error message

Expecting a PCollection argument.

What it means

PTransform._check_pcollection validates that an argument passed to expand() is actually a PCollection instance. Raising TransformError here means a non-PCollection (list, dict, PBegin, DeferredExpression, etc.) was passed where a PCollection is required.

Solutions

1. Wrap raw iterables with beam.pipeline | beam.Create(items) before passing them
2. Ensure the argument comes from a prior transform's output (a real PCollection)
3. Check for reassignments that overwrote the PCollection variable
4. Pass side-input data via beam.pvalue.AsList/AsDict/AsSingleton instead of as the main input

Example fix

// before
my_transform.expand([1, 2, 3])
// after
pcoll = p | 'Create' >> beam.Create([1, 2, 3])
my_transform.expand(pcoll)

if not isinstance(arg, pvalue.PCollection):
    arg = pipeline | 'CreateInput' >> beam.Create(arg)

def is_pcollection(x):
    return isinstance(x, pvalue.PCollection) and x.pipeline is not None

try:
    result = my_transform.expand(arg)
except error.TransformError as ex:
    logger.error('bad expand input: %s', ex)
    raise

When it happens

Trigger: Calling an expand() that checks its inputs with something like a plain Python list, a dict, a string, or a materialized value instead of a PCollection produced by a prior transform.

Common situations: Feeding raw lists into custom transforms instead of beam.Create(...); reusing a variable that was reassigned to non-PCollection data; mistakenly passing a side input value as the main input.

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

• A sink must inherit iobase.Sink, iobase.NativeSink, or be a…
• Cannot encode payload for WriteToPubSub. Expected valid…
• Cannot interpret as seconds.
• Cannot interpret as subseconds.
• compression_type must be CompressionType object but was

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/ptransform.py:569

  def __str__(self):
    return '<%s>' % self._str_internal()

  def __repr__(self):
    return '<%s at %s>' % (self._str_internal(), hex(id(self)))

  def _str_internal(self):
    return '%s(PTransform)%s%s%s' % (
        self.__class__.__name__,
        ' label=[%s]' % self.label if
        (hasattr(self, 'label') and self.label) else '',
        ' inputs=%s' % str(self.inputs) if
        (hasattr(self, 'inputs') and self.inputs) else '',
        ' side_inputs=%s' % str(self.side_inputs) if self.side_inputs else '')

  def _check_pcollection(self, pcoll):
    # type: (pvalue.PCollection) -> None
    if not isinstance(pcoll, pvalue.PCollection):
      raise error.TransformError('Expecting a PCollection argument.')
    if not pcoll.pipeline:
      raise error.TransformError('PCollection not part of a pipeline.')

  def get_windowing(self, inputs):
    # type: (Any) -> Windowing

    """Returns the window function to be associated with transform's output.

    By default most transforms just return the windowing function associated
    with the input PCollection (or the first input if several).
    """
    if inputs:
      return inputs[0].windowing
    else:
      from apache_beam.transforms.core import Windowing
      from apache_beam.transforms.window import GlobalWindows

      # TODO(robertwb): Return something compatible with every windowing?

View on GitHub (pinned to 12126d8942)