apache/beam · error · ValueError

PCollection of size with more than one element accessed as…

Error message

PCollection of size %d with more than one element accessed as a singleton view. First two elements encountered are "%s", "%s".

What it means

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.

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

Example fix

// before
beam.Map(beam.pvalue.AsSingleton(events), compute)
// after
beam.Map(beam.pvalue.AsSingleton(events | beam.CombineGlobally(sum)), compute)

Defensive patterns

Strategy: validation

Validate before calling

# inspect side input size before use, e.g. in a prior stage
count = (pcoll | beam.CountGlobally())
# or defensively: use AsIter and assert length in the DoFn

Try / catch

try:
    value = beam.pvalue.AsSingleton(pcoll)
except ValueError as e:
    # fall back to first/combined element handling
    value = None

Prevention

Combine or deduplicate singleton-view PCollections
Prefer AsIter when multiplicity is possible
Test side inputs with realistic data volumes

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/pvalue.py:519

    self.default_value = default_value

  def __repr__(self):
    return 'AsSingleton(%s)' % self.pvalue

  def _view_options(self):
    base = super()._view_options()
    if self.default_value != AsSingleton._NO_DEFAULT:
      return dict(base, default=self.default_value)
    return base

  @staticmethod
  def _from_runtime_iterable(it, options):
    head = list(itertools.islice(it, 2))
    if not head:
      return options.get('default', EmptySideInput())
    elif len(head) == 1:
      return head[0]
    raise ValueError(
        'PCollection of size %d with more than one element accessed as a '
        'singleton view. First two elements encountered are "%s", "%s".' %
        (len(head), str(head[0]), str(head[1])))

  @property
  def element_type(self):
    return self.pvalue.element_type


class AsIter(AsSideInput):
  """Marker specifying that an entire PCollection is to be used as a side input.

  When a PCollection is supplied as a side input to a PTransform, it is
  necessary to indicate whether the entire PCollection should be made available
  as a PTransform side argument (in the form of an iterable), or whether just
  one value should be pulled from the PCollection and supplied as the side
  argument (as an ordinary value).

View on GitHub (pinned to 12126d8942)