apache/beam · error · ValueError

Input to Flatten must be an iterable. Got a value of type

Error message

Input to Flatten must be an iterable. Got a value of type %s instead.

What it means

Raised by Flatten._extract_input_pvalues when the input cannot be converted to a tuple, i.e. it is not an iterable of PCollections. Flatten needs a collection of input PCollections to merge; a single bare PCollection or a non-iterable value cannot be flattened.

Solutions

Pass a tuple/list of PCollections: result = (pc1, pc2, pc3) | beam.Flatten().
If inputs are in a list variable: result = pcoll_list | beam.Flatten().
To pass a single collection through unchanged, skip Flatten or wrap it: (single_pcoll,) | beam.Flatten().
Verify the value is not None/exhausted before piping.

Example fix

// before
merged = pc | beam.Flatten()  # pc is a single PCollection
// after
merged = [pc1, pc2, pc3] | beam.Flatten()

Defensive patterns

Strategy: type-guard

Validate before calling

assert isinstance(inputs, (list, tuple)) and all(isinstance(x, PCollection) for x in inputs), 'Flatten needs an iterable of PCollections'

Type guard

def is_pcollection_iterable(v):
    try:
        items = list(v)
    except TypeError:
        return False
    return all(isinstance(x, PCollection) for x in items)

Try / catch

try:
    merged = inputs | beam.Flatten()
except ValueError as e:
    log.error('Flatten input not iterable of PCollections: %s', e)

Prevention

Pass tuples/lists of PCollections, never a single PCollection
Check for None or exhausted generators before piping
Wrap single collections as (pcoll,)

When it happens

Trigger: pc | beam.Flatten() where pc is a single PCollection rather than a tuple/list of them; passing a dict or scalar; calling Flatten on a generator that has been exhausted (raising TypeError on tuple()).

Common situations: Mistakenly piping one PCollection directly to Flatten instead of a tuple; building the input list conditionally and ending up with None; passing a dict where a list was intended.

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/737b891851b4ad1f. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/transforms/core.py:4110

  Args:
    **kwargs: Accepts a single named argument "pipeline", which specifies the
      pipeline that "owns" this PTransform. Ordinarily Flatten can obtain this
      information from one of the input PCollections, but if there are none (or
      if there's a chance there may be none), this argument is the only way to
      provide pipeline information and should be considered mandatory.
  """
  def __init__(self, **kwargs):
    super().__init__()
    self.pipeline = kwargs.pop(
        'pipeline', None)  # type: typing.Optional[Pipeline]
    if kwargs:
      raise ValueError('Unexpected keyword arguments: %s' % list(kwargs))

  def _extract_input_pvalues(self, pvalueish):
    try:
      pvalueish = tuple(pvalueish)
    except TypeError:
      raise ValueError(
          'Input to Flatten must be an iterable. '
          'Got a value of type %s instead.' % type(pvalueish))

    # Spot check to see if any of the items are iterables of PCollections
    # and raise an error if so. This is always a user-error
    for idx, item in enumerate(pvalueish):
      if isinstance(item, (list, tuple)) and any(
          isinstance(sub_item, pvalue.PCollection) for sub_item in item):
        raise TypeError(
            'Inputs to Flatten cannot include an iterable of PCollections. '
            f'(input at index {idx}: "{item}")')
    return pvalueish, pvalueish

  def expand(self, pcolls):
    windowing = self.get_windowing(pcolls)
    for pcoll in pcolls:
      self._check_pcollection(pcoll)
      if pcoll.windowing != windowing:

View on GitHub (pinned to 12126d8942)