apache/beam · error · BeamAssertException

Failed assert: element

Error message

Failed assert: element {} not found in window {}:{}

What it means

In equal_to_per_window's match(), after the window is found, the matcher removes the actual element from the expected list for that window via list.remove(). If the element's value is not present in that window's expected list, remove() raises ValueError, which is converted to BeamAssertException naming the missing element, its window, and the expected contents.

Solutions

1. Correct the expected element list for that window to match the pipeline's actual output.
2. Debug why the pipeline emits a different value (inspect the transform producing it).
3. Compare with exact types (str vs bytes, int vs float) — Python equality is type-sensitive in remove().

Example fix

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

# sanity-check expected contents against a dry run of the transform logic
for win, elems in expected.items():
    assert all(isinstance(e, str) for e in elems), 'type mismatch in expected elements'

def window_has_element(wv, expected) -> bool:
    return wv.value in expected.get(wv.windows[0], [])

from apache_beam.testing.util import BeamAssertException
try:
    assert_that(pcoll, equal_to_per_window(expected), reify_windows=True)
except BeamAssertException as e:
    if 'not found in window' in str(e):
        logging.error('Element mismatch: %s', e)
    else:
        raise

When it happens

Trigger: An actual element arrives in a known window but its value differs from every expected value in that window's list (e.g. expected ['a'] but the pipeline produced 'b', or a different timestamped encoding/None vs value).

Common situations: Expected/actual value mismatches from transformations in the pipeline under test (e.g. forgetting a map step); float precision differences; comparing encoded vs decoded values; wrong expected payload for one window while others match.

Related errors

• Failed assert: Received element
• Failed assert: unmatched elements
• 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/5ba680bd261d8cb0. Report an issue: GitHub.

Appendix: source

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

    # Match the given windowed value to an expected window. Fails if the window
    # doesn't exist or the element wasn't found in the window.
    def match(windowed_value):
      actual = windowed_value.value
      window_key = windowed_value.windows[0]
      try:
        _expected[window_key]
      except KeyError:
        raise BeamAssertException(
            'Failed assert: window {} not found in any expected ' \
            'windows {}'.format(window_key, list(_expected.keys())))\

      # Remove any matched elements from the window. This is used later on to
      # assert that all elements in the window were matched with actual
      # elements.
      try:
        _expected[window_key].remove(actual)
      except ValueError:
        raise BeamAssertException(
            '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]:

View on GitHub (pinned to 12126d8942)