apache/beam · error · ValueError

Unknown type of expected outcome: %r

Error message

Unknown type of expected outcome: %r

What it means

Raised by _assert_split_at_fraction_behavior when the expected_outcome argument is not one of the ExpectedSplitOutcome enum values (MUST_FAIL, MUST_BE_CONSISTENT_IF_SUCCEEDS). It is a guard against passing an unknown or mis-spelled outcome specifier.

Source

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

      raise ValueError(
          'Expected split of source %r at fraction %r to be '
          'successful after reading %d elements. But '
          'the split failed.' %
          (source, split_fraction, num_items_to_read_before_split))
  elif expected_outcome == ExpectedSplitOutcome.MUST_FAIL:
    if split_result:
      raise ValueError(
          'Expected split of source %r at fraction %r after '
          'reading %d elements to fail. But splitting '
          'succeeded with result %r.' % (
              source,
              split_fraction,
              num_items_to_read_before_split,
              split_result))

  elif (expected_outcome
        != ExpectedSplitOutcome.MUST_BE_CONSISTENT_IF_SUCCEEDS):
    raise ValueError('Unknown type of expected outcome: %r' % expected_outcome)
  current_items.extend([value for value in reader_iter])

  residual_range = (
      split_result[0], stop_position_before_split) if split_result else None

  return _verify_single_split_fraction_result(
      source,
      expected_items,
      current_items,
      split_result,
      (range_tracker.start_position(), range_tracker.stop_position()),
      residual_range,
      split_fraction)


def _range_to_str(start, stop):
  return '[' + (str(start) + ',' + str(stop) + ')')

View on GitHub (pinned to 12126d8942)

Solutions

  1. Use a valid member: ExpectedSplitOutcome.MUST_FAIL, ExpectedSplitOutcome.MUST_BE_CONSISTENT_IF_SUCCEEDS (or MUST_SUCCEED where supported).
  2. Print ExpectedSplitOutcome.__members__ to see the allowed values before passing one.
  3. If the outcome comes from external config, validate it against the enum before calling the assertion.
  4. Check imports — comparing against a similarly named constant from another module yields an unknown value.

Example fix

// before
assert_split_at_fraction_binary(source, 'MUST_SUCCEED', fraction=0.5)
// after
from apache_beam.io.iobase import ExpectedSplitOutcome
assert_split_at_fraction_binary(source, ExpectedSplitOutcome.MUST_SUCCEED, fraction=0.5)
Defensive patterns

Strategy: type-guard

Validate before calling

from apache_beam.io.iobase import ExpectedSplitOutcome
if not isinstance(expected_outcome, ExpectedSplitOutcome):
    raise TypeError(f'expected_outcome must be an ExpectedSplitOutcome, got {expected_outcome!r}')

Type guard

def is_expected_split_outcome(v):
    return isinstance(v, ExpectedSplitOutcome)

Try / catch

try:
    assert_split_at_fraction_binary(source, outcome)
except ValueError as e:
    if 'Unknown type of expected outcome' in str(e):
        logging.error('Bad expected_outcome: %r', outcome)

Prevention

When it happens

Trigger: Passing a raw string like 'MUST_SUCCEED', None, a boolean, or an invalid enum member to assert_split_at_fraction_behavior / assert_split_at_fraction_binary as expected_outcome.

Common situations: Typo in the ExpectedSplitOutcome member name; constructing the enum value from config or a variable that holds the wrong type; older code written against a different enum variant set.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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