apache/beam · error · BeamAssertException

Failed assert: pcol is empty

Error message

Failed assert: pcol is empty

What it means

BeamAssertException raised by the `_not_empty` matcher returned by `assert_that(..., equal_to)`-style helpers when the pipeline's output PCollection is completely empty. Beam throws it because a caller asked to assert that the PCollection has data but the transform produced nothing, so the assertion (or a check for non-emptiness) failed at runtime during pipeline evaluation.

Solutions

1. Inspect the upstream transforms and source: relax the filter predicate or fix the source so at least one element is produced.
2. If emptiness is expected/acceptable, remove the non-emptiness assert or assert on the empty result explicitly instead.
3. Add logging/counting of input and output elements to find where records are dropped.

Example fix

// before
assert_that(result, _not_empty, label='nonempty')
// after
# only assert if data is guaranteed; otherwise assert on actual contents
assert_that(result, equal_to(expected_records), label='contents')

# assert only on pcollections known to have data
count = (pcoll | 'count' >> beam.combiners.Count.Globally())
# or check upstream source/filter logic before asserting non-emptiness

When it happens

Trigger: Calling `assert_that(pcoll, _not_empty)` (directly or via equal_to-style matchers) on a PCollection whose evaluation yields zero elements — e.g. a filter/par-do upstream eliminated all records, or the source produced no data.

Common situations: Test pipelines where an upstream `Filter` removed everything, reading from an empty file/table/topic, a side-input or window that produced no elements, or a mistaken filter predicate in test code.

Understand the failure class

Background: EmptyResultError / "no results found": when an API or scraper succeeds but returns zero rows — this error's family across 9 libraries.

Related errors

• assert_that must be used within a beam.Pipeline context…
• Failed assert: nothing matches the criterion
• passert.Sum( ) = , want
• %s
• The pipeline contains abandoned PAssert(s).

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

Appendix: source

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

def is_empty():
  def _empty(actual):
    actual = list(actual)
    if actual:
      raise BeamAssertException('Failed assert: [] == %r' % actual)

  return _empty


def is_not_empty():
  """
  This is test method which makes sure that the pcol is not empty and it has
  some data in it.
  :return:
  """
  def _not_empty(actual):
    actual = list(actual)
    if not actual:
      raise BeamAssertException('Failed assert: pcol is empty')

  return _not_empty


def assert_that(
    actual,
    matcher,
    label='assert_that',
    reify_windows=False,
    use_global_window=True):
  """A PTransform that checks a PCollection has an expected value.

  Note that assert_that should be used only for testing pipelines since the
  check relies on materializing the entire PCollection being checked.

  Args:
    actual: A PCollection.
    matcher: A matcher function taking as argument the actual value of a

View on GitHub (pinned to 12126d8942)