apache/beam · error · ValueError

reference_source_info must a three-tuple where firstitem of…

Error message

reference_source_info must a three-tuple where firstitem of the tuple gives a iobase.BoundedSource. Received: %r

What it means

In Beam's source_test_utils, assert_sources_equal_reference_source requires reference_source_info to be a three-element tuple whose first element is an iobase.BoundedSource (source, options, desired bundle size). It raises ValueError otherwise because the reference source is unpacked via read_from_source(*reference_source_info).

Solutions

  1. Pass a 3-tuple: (bounded_source, read_options, desired_bundle_size)
  2. Ensure the first element is an instance of iobase.BoundedSource, not the legacy Source class
  3. Wrap the source in a list of tuples form consistent with sources_info
  4. Check tuple vs list — must be an actual tuple

Example fix

// before
assert_sources_equal_reference_source((source, pipeline_options), ...)
// after
assert_sources_equal_reference_source((source, pipeline_options, 1000), ...)
Defensive patterns

Strategy: type-guard

Validate before calling

from apache_beam.io import iobase
assert isinstance(ref, tuple) and len(ref) == 3 and isinstance(ref[0], iobase.BoundedSource)

Type guard

def is_valid_source_info(info):
    return isinstance(info, tuple) and len(info) == 3 and isinstance(info[0], iobase.BoundedSource)

Try / catch

try:
    source_test_utils.assert_sources_equal_reference_source(ref, sources)
except ValueError as e:
    logger.error('Bad source test input: %s', e)

Prevention

When it happens

Trigger: Calling assert_sources_equal_reference_source with a two-element tuple, a list instead of a tuple, or a first element that is a custom Source rather than a BoundedSource subclass.

Common situations: Writing new BoundedSource unit tests and passing (source, options) forgetting the bundle-size hint, or migrating tests from the old Source API to BoundedSource.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/io/source_test_utils.py:143

        (Tuple[~apache_beam.io.iobase.BoundedSource, int, int]):
      a three-tuple that gives the reference
      :class:`~apache_beam.io.iobase.BoundedSource`, position to start
      reading at, and position to stop reading at.
    sources_info\
        (Iterable[Tuple[~apache_beam.io.iobase.BoundedSource, int, int]]):
      a set of sources. Each source is a three-tuple that is of the same
      format described above.

  Raises:
    ValueError: if the set of data produced by the reference source
      and the given set of sources are not equivalent.

  """

  if not (isinstance(reference_source_info, tuple) and
          len(reference_source_info) == 3 and
          isinstance(reference_source_info[0], iobase.BoundedSource)):
    raise ValueError(
        'reference_source_info must a three-tuple where first'
        'item of the tuple gives a '
        'iobase.BoundedSource. Received: %r' % reference_source_info)
  reference_records = read_from_source(*reference_source_info)

  source_records = []
  for source_info in sources_info:
    assert isinstance(source_info, tuple)
    assert len(source_info) == 3
    if not (isinstance(source_info, tuple) and len(source_info) == 3 and
            isinstance(source_info[0], iobase.BoundedSource)):
      raise ValueError(
          'source_info must a three tuple where first'
          'item of the tuple gives a '
          'iobase.BoundedSource. Received: %r' % source_info)
    if (type(reference_source_info[0].default_output_coder())
        != type(source_info[0].default_output_coder())):
      raise ValueError(

View on GitHub (pinned to 12126d8942)