{"record":{"id":"9fe17f166a00409d","repo":"apache/beam","slug":"pcollection-of-size-d-with-more-than-one-element-accessed-as","errorCode":null,"errorMessage":"PCollection of size %d with more than one element accessed as a singleton view. First two elements encountered are \"%s\", \"%s\".","messagePattern":"PCollection of size (.+?) with more than one element accessed as a singleton view\\. First two elements encountered are \"(.+?)\", \"(.+?)\"\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/pvalue.py","lineNumber":519,"sourceCode":"    self.default_value = default_value\n\n  def __repr__(self):\n    return 'AsSingleton(%s)' % self.pvalue\n\n  def _view_options(self):\n    base = super()._view_options()\n    if self.default_value != AsSingleton._NO_DEFAULT:\n      return dict(base, default=self.default_value)\n    return base\n\n  @staticmethod\n  def _from_runtime_iterable(it, options):\n    head = list(itertools.islice(it, 2))\n    if not head:\n      return options.get('default', EmptySideInput())\n    elif len(head) == 1:\n      return head[0]\n    raise ValueError(\n        'PCollection of size %d with more than one element accessed as a '\n        'singleton view. First two elements encountered are \"%s\", \"%s\".' %\n        (len(head), str(head[0]), str(head[1])))\n\n  @property\n  def element_type(self):\n    return self.pvalue.element_type\n\n\nclass AsIter(AsSideInput):\n  \"\"\"Marker specifying that an entire PCollection is to be used as a side input.\n\n  When a PCollection is supplied as a side input to a PTransform, it is\n  necessary to indicate whether the entire PCollection should be made available\n  as a PTransform side argument (in the form of an iterable), or whether just\n  one value should be pulled from the PCollection and supplied as the side\n  argument (as an ordinary value).\n","sourceCodeStart":501,"sourceCodeEnd":537,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/pvalue.py#L501-L537","documentation":"When a PCollection wrapped as a singleton view (AsSingleton) is accessed via _from_runtime_iterable, Beam slices the first two elements to detect size. If more than one element exists, the view cannot pick a single value, so it raises this ValueError, reporting the size and the first two elements encountered.","triggerScenarios":"pcoll | beam.Map(beam.pvalue.AsSingleton(other_pcoll), fn) where other_pcoll contains 2+ elements; also empty-case default missing and multiple elements arrive at runtime.","commonSituations":"Assuming a 'unique key' side input is actually unique after a join/flat expansion; pipeline data drift introduces a duplicate; test fixtures accidentally produce multiple rows.","solutions":["Ensure the side-input PCollection has exactly one element (e.g. CombineGlobally, or beam.Map(lambda xs: xs[0]) over a list)","Use beam.pvalue.AsDict or AsMultimap if the input is naturally multi-valued","Use beam.pvalue.AsIter to receive an iterable instead of a single value","Pass default=... to AsSingleton only fixes the empty case, not the multi-element case; filter/pick deterministically first"],"exampleFix":"// before\nbeam.Map(beam.pvalue.AsSingleton(events), compute)\n// after\nbeam.Map(beam.pvalue.AsSingleton(events | beam.CombineGlobally(sum)), compute)","handlingStrategy":"validation","validationCode":"# inspect side input size before use, e.g. in a prior stage\ncount = (pcoll | beam.CountGlobally())\n# or defensively: use AsIter and assert length in the DoFn","typeGuard":null,"tryCatchPattern":"try:\n    value = beam.pvalue.AsSingleton(pcoll)\nexcept ValueError as e:\n    # fall back to first/combined element handling\n    value = None","preventionTips":["Combine or deduplicate singleton-view PCollections","Prefer AsIter when multiplicity is possible","Test side inputs with realistic data volumes"],"tags":["python","apache-beam","singleton-view"],"backgroundTag":"value-out-of-range","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"}