apache/beam · error · ValueError

no matching row found for row_key: %s with row_filter=%s

Error message

no matching row found for row_key: %s with row_filter=%s

What it means

Raised by BigTableEnrichmentHandler.__call__ when a BigTable lookup for the computed row key returned no rows and the handler's exception_level is set to RAISE (a ValueError). The handler can instead log a warning (WARN) or continue silently, but at RAISE level an unmatched row key fails the element. A related KeyError path indicates the row key field itself was absent from the input row.

Source

Thrown at sdks/python/apache_beam/transforms/enrichment_handlers/bigtable.py:143

        row_key = row_key_str.encode(self._encoding)
      row = self._table.read_row(row_key, filter_=self._row_filter)
      if row:
        for cf_id, cf_v in row.cells.items():
          response_dict[cf_id] = {}
          for col_id, col_v in cf_v.items():
            if self._include_timestamp:
              response_dict[cf_id][col_id.decode(self._encoding)] = [
                  (v.value.decode(self._encoding), v.timestamp) for v in col_v
              ]
            else:
              response_dict[cf_id][col_id.decode(
                  self._encoding)] = col_v[0].value.decode(self._encoding)
      elif self._exception_level == ExceptionLevel.WARN:
        _LOGGER.warning(
            'no matching row found for row_key: %s '
            'with row_filter: %s' % (row_key_str, self._row_filter))
      elif self._exception_level == ExceptionLevel.RAISE:
        raise ValueError(
            'no matching row found for row_key: %s '
            'with row_filter=%s' % (row_key_str, self._row_filter))
    except KeyError:
      raise KeyError('row_key %s not found in input PCollection.' % row_key_str)
    except NotFound:
      raise NotFound(
          'GCP BigTable cluster `%s:%s:%s` not found.' %
          (self._project_id, self._instance_id, self._table_id))
    except Exception as e:
      raise e

    return request, beam.Row(**response_dict)

  def __exit__(self, exc_type, exc_val, exc_tb):
    """Clean the instantiated BigTable client."""
    self.client = None
    self.instance = None
    self._table = None

View on GitHub (pinned to 12126d8942)

Solutions

Verify the row_key_fn/row_key produces keys that exactly match keys written to BigTable (encoding, prefix, zero-padding).
Check the configured row_filter and table/instance ids point at the data you expect.
Set exception_level=ExceptionLevel.WARN if unmatched rows should be tolerated instead of failing the pipeline.
Fix upstream data so the referenced rows exist before enrichment runs.

Example fix

# before
h = bigtable.BigTableEnrichmentHandler(..., exception_level=ExceptionLevel.RAISE)
# after (tolerate missing rows)
h = bigtable.BigTableEnrichmentHandler(..., exception_level=ExceptionLevel.WARN)

Defensive patterns

Strategy: fallback

Validate before calling

key = row_key_fn(row)
# pre-check against a known key set or ensure upstream write completed before enrichment

Type guard

def extractable_key(row, field='key'):
    return row if field in row._asdict() else None

Try / catch

try:
    enriched = pcoll | Enrichment(handler)
except ValueError as e:
    if 'no matching row found' in str(e):
        logging.warning('unmatched BigTable key, using original row: %s', e)
    else:
        raise

Prevention

Verify key formatting (padding, prefixes, encoding) matches the writer.
Set exception_level=WARN when occasional misses are acceptable.
Confirm the row exists in BigTable (e.g. via a manual read) before pipeline runs.
Double-check instance_id, table_id, and row_filter settings.

When it happens

Trigger: Calling the handler on a row whose extracted row_key does not exist in the BigTable (given the configured row_filter), with BigTableEnrichmentHandler(..., exception_level=ExceptionLevel.RAISE).

Common situations: Row keys missing due to data lag (enrichment source not yet populated); wrong row key format (e.g. missing prefix/padding used by the writing pipeline); row_filter excluding the row; pointing at the wrong table or instance.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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