apache/beam · error · ValueError

Source %r only reads a single item.

Error message

Source %r only reads a single item.

What it means

assert_split_at_fraction_exhaustive requires at least two items because a split is only non-trivial when both primary and residual are non-empty; a single-item source cannot produce a meaningful split, so the harness raises this ValueError.

Solutions

1. Provide a source with at least two items over the tested range.
2. Widen start_position/stop_position so the range spans multiple records.
3. Use assert_split_at_fraction_binary on a single-item source only if you expect all splits to fail, rather than the exhaustive test.
4. Generate synthetic multi-item data in the test fixture.

Example fix

// before
assert_split_at_fraction_exhaustive(source_from_items(['only']), 0, 1)
// after
assert_split_at_fraction_exhaustive(source_from_items(['a', 'b', 'c']), 0, 3)

items = read_from_source(source, start_position, stop_position)
if len(items) < 2:
    pytest.skip('need >=2 items for exhaustive split test')

try:
    assert_split_at_fraction_exhaustive(source, start, stop)
except ValueError as e:
    if 'single item' in str(e):
        pytest.skip(f'source too small: {e}')

When it happens

Trigger: Calling assert_split_at_fraction_exhaustive on a source whose range [start_position, stop_position) contains exactly one item.

Common situations: Tiny hand-built test sources (e.g. ['a'] or range(1)); overly narrow start/stop positions trimming the data to one record; a filter in the source leaving a single element.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Expected split of source %r at fraction %r after reading
• Items obtained by reading the source %r for primary and…
• Source %r is empty.
• SplitAtFraction test completed vacuously: no non-trivial…
• SplitAtFraction test completed vacuously: no successful…

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

Appendix: source

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

  least one item) and the results are consistent if a split succeeds.
  Verifies multi threaded splitting as well.

  Args:
    source (~apache_beam.io.iobase.BoundedSource): the source to perform
      dynamic splitting on.
    perform_multi_threaded_test (bool): if :data:`True` performs a
      multi-threaded test, otherwise this test is skipped.

  Raises:
    ValueError: if the exhaustive splitting test fails.
  """

  expected_items = read_from_source(source, start_position, stop_position)
  if not expected_items:
    raise ValueError('Source %r is empty.' % source)

  if len(expected_items) == 1:
    raise ValueError('Source %r only reads a single item.' % source)

  all_non_trivial_fractions = []

  any_successful_fractions = False
  any_non_trivial_fractions = False

  for i in range(len(expected_items)):
    stats = SplitFractionStatistics([], [])

    assert_split_at_fraction_binary(
        source, expected_items, i, 0.0, None, 1.0, None, stats)

    if stats.successful_fractions:
      any_successful_fractions = True
    if stats.non_trivial_fractions:
      any_non_trivial_fractions = True

    all_non_trivial_fractions.append(stats.non_trivial_fractions)

View on GitHub (pinned to 12126d8942)