apache/beam · error · BeamAssertException

Failed assert: unmatched elements

Error message

Failed assert: unmatched elements {} in window {}

What it means

After matching all received elements, equal_to_per_window checks that every window's expected list is empty (all expected elements were consumed by actual matches). Any leftover expected elements for a window means the pipeline produced fewer/different elements than expected, so BeamAssertException lists the unmatched elements and the window.

Solutions

1. Remove or correct the unmatched expected elements/windows to reflect actual output.
2. Debug why the pipeline did not emit those elements (check filters, conditions, input data).
3. Add logging before the assertion to dump actual elements per window.

Example fix

// before
assert_that(pcoll, equal_to_per_window({win: ['a', 'b']}), reify_windows=True)  # only 'a' emitted
// after
assert_that(pcoll, equal_to_per_window({win: ['a']}), reify_windows=True)

# cross-check expected totals against input record counts
expected_total = sum(len(v) for v in expected.values())
assert expected_total <= num_input_records, 'more expected than input elements'

def no_leftover_expectations(expected) -> bool:
    return all(not v for v in expected.values())  # after a completed match

from apache_beam.testing.util import BeamAssertException
try:
    assert_that(pcoll, equal_to_per_window(expected), reify_windows=True)
except BeamAssertException as e:
    if 'unmatched elements' in str(e):
        logging.error('Missing outputs: %s', e)
    else:
        raise

When it happens

Trigger: The expected dict contains an element (or an entire window) that never appeared in the actual output — e.g. expected {win: ['a','b']} but only 'a' was emitted, or an expected window received no data at all.

Common situations: Pipeline drops or filters records that the test expected; partial batch/test data; a transform emits fewer outputs (e.g. flat_map skipping items); duplicated windows in expectations that never receive data.

Related errors

• Failed assert: element
• Failed assert: Received element
• Failed assert: window
• Failed assert: [] == %r
• Failed assert: %r == %r

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

Appendix: source

Thrown at sdks/python/apache_beam/testing/util.py:144

            'Failed assert: element {} not found in window ' \
            '{}:{}'.format(actual, window_key, _expected[window_key]))\

    # Run the matcher for each window and value pair. Fails if the
    # windowed_value is not a TestWindowedValue.
    for windowed_value in value:
      if not isinstance(windowed_value, TestWindowedValue):
        raise BeamAssertException(
            'Failed assert: Received element {} is not of type ' \
            'TestWindowedValue. Did you forget to set reify_windows=True ' \
            'on the assertion?'.format(windowed_value))
      match(windowed_value)

    # Finally, some elements may not have been matched. Assert that we removed
    # all the elements that we received from the expected list. If the list is
    # non-empty, then there are unmatched elements.
    for win in _expected:
      if _expected[win]:
        raise BeamAssertException(
            'Failed assert: unmatched elements {} in window {}'.format(
                _expected[win], win))


def equal_to_per_window(expected_window_to_elements):
  """Matcher used by assert_that to check to assert expected windows.

  The 'assert_that' statement must have reify_windows=True. This assertion works
  when elements are emitted and are finally checked at the end of the window.

  Arguments:
    expected_window_to_elements: A dictionary where the keys are the windows
      to check and the values are the elements associated with each window.
  """

  return _EqualToPerWindowMatcher(expected_window_to_elements)

View on GitHub (pinned to 12126d8942)