{"record":{"id":"88449470c732fcd7","repo":"apache/beam","slug":"inputs-to-flatten-cannot-include-an-iterable-of-pcollections","errorCode":null,"errorMessage":"Inputs to Flatten cannot include an iterable of PCollections. (input at index {idx}: \"{item}\")","messagePattern":"Inputs to Flatten cannot include an iterable of PCollections\\. \\(input at index (.+?): \"(.+?)\"\\)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/core.py","lineNumber":4119,"sourceCode":"    self.pipeline = kwargs.pop(\n        'pipeline', None)  # type: typing.Optional[Pipeline]\n    if kwargs:\n      raise ValueError('Unexpected keyword arguments: %s' % list(kwargs))\n\n  def _extract_input_pvalues(self, pvalueish):\n    try:\n      pvalueish = tuple(pvalueish)\n    except TypeError:\n      raise ValueError(\n          'Input to Flatten must be an iterable. '\n          'Got a value of type %s instead.' % type(pvalueish))\n\n    # Spot check to see if any of the items are iterables of PCollections\n    # and raise an error if so. This is always a user-error\n    for idx, item in enumerate(pvalueish):\n      if isinstance(item, (list, tuple)) and any(\n          isinstance(sub_item, pvalue.PCollection) for sub_item in item):\n        raise TypeError(\n            'Inputs to Flatten cannot include an iterable of PCollections. '\n            f'(input at index {idx}: \"{item}\")')\n    return pvalueish, pvalueish\n\n  def expand(self, pcolls):\n    windowing = self.get_windowing(pcolls)\n    for pcoll in pcolls:\n      self._check_pcollection(pcoll)\n      if pcoll.windowing != windowing:\n        _LOGGER.warning(\n            'All input pcollections must have the same window. Windowing for '\n            'flatten set to %s, windowing of pcoll %s set to %s',\n            windowing,\n            pcoll,\n            pcoll.windowing)\n    is_bounded = all(pcoll.is_bounded for pcoll in pcolls)\n    return pvalue.PCollection(self.pipeline, is_bounded=is_bounded)\n","sourceCodeStart":4101,"sourceCodeEnd":4137,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/core.py#L4101-L4137","documentation":"Raised by Flatten._extract_input_pvalues when one element of the input is itself a list/tuple containing PCollections — i.e. a nested iterable of PCollections inside the flatten input. Beam treats this as an always-a-user-error structure and rejects it with a TypeError, reporting the index and the offending item.","triggerScenarios":"Passing something like [pc1, [pc2, pc3]] or (pc1, (pc2, pc3)) to Flatten; grouping PCollections into sub-lists and flattening the outer list; results of functions that return lists of PCollections inserted into a parent list.","commonSituations":"Building inputs programmatically where some entries are already collections of PCollections; mixing grouped and ungrouped inputs from helper functions.","solutions":["Flatten the nested structure before piping: inputs = [pc1] + [pc2, pc3].","Use itertools.chain or a comprehension to produce a flat list of PCollections.","Apply Flatten twice if nested grouping is intentional: flatten inner groups first, then the outer list.","Assert all elements are PCollection instances before calling Flatten."],"exampleFix":"// before\nmerged = [pc1, [pc2, pc3]] | beam.Flatten()\n// after\nmerged = [pc1, pc2, pc3] | beam.Flatten()","handlingStrategy":"validation","validationCode":"for i, item in enumerate(inputs):\n    assert not (isinstance(item, (list, tuple)) and any(isinstance(s, PCollection) for s in item)), f'nested PCollections at index {i}'","typeGuard":"def is_flat_pcoll_list(v):\n    return not any(isinstance(x, (list, tuple)) for x in v)","tryCatchPattern":"try:\n    merged = inputs | beam.Flatten()\nexcept TypeError as e:\n    log.error('Nested PCollection iterable: %s', e)","preventionTips":["Flatten helper-function outputs before combining","Use list concatenation/itertools.chain to keep one flat list","Type-check inputs before piping"],"tags":["python","apache-beam","flatten","nested-input"],"backgroundTag":"invalid-argument-format","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}