apache/beam · error · ValueError

Please specify exactly one of a `entity_id` or a lambda func

Error message

Please specify exactly one of a `entity_id` or a lambda function with `entity_row_fn` to extract the entity id from the input row.

What it means

Raised by `_validate_entity_key_exists` from `__init__` when the handler is constructed with neither `entity_id` nor `entity_row_fn`, or with both. The handler needs exactly one way to derive the entity key (a static column name, or a lambda building the key from the row) to look up features in the Feast online store.

Source

Thrown at sdks/python/apache_beam/transforms/enrichment_handlers/feast_feature_store.py:78

      bool(feature_names and feature_service_name)):
    raise ValueError(
        'Please provide exactly one of a list of feature names to fetch '
        'from online store (`feature_names`) or a feature service name for '
        'the Feast online feature store (`feature_service_name`).')


def _validate_feature_store_yaml_path_exists(fs_yaml_file):
  """Check if the feature store yaml path exists."""
  if not FileSystems.exists(fs_yaml_file):
    raise ValueError(
        'The feature store yaml path (%s) does not exist.' % fs_yaml_file)


def _validate_entity_key_exists(entity_id, entity_row_fn):
  """Checks if the entity key or a lambda to build entity key exists."""
  if ((not entity_row_fn and not entity_id) or
      bool(entity_row_fn and entity_id)):
    raise ValueError(
        "Please specify exactly one of a `entity_id` or a lambda "
        "function with `entity_row_fn` to extract the entity id "
        "from the input row.")


class FeastFeatureStoreEnrichmentHandler(EnrichmentSourceHandler[beam.Row,
                                                                 beam.Row]):
  """Enrichment handler to interact with the Feast feature store.

  To specify the features to fetch from Feast online store,
  please specify exactly one of `feature_names` or `feature_service_name`.

  Use this handler with :class:`apache_beam.transforms.enrichment.Enrichment`
  transform. To filter the features to enrich, use the `join_fn` param in
  :class:`apache_beam.transforms.enrichment.Enrichment`.
  """
  def __init__(
      self,

View on GitHub (pinned to 12126d8942)

Solutions

Provide exactly one: a column name via `entity_id`, or a key-building lambda via `entity_row_fn`.
Remove the redundant second option when both are set.
Use `entity_row_fn` when the entity key must be composed from multiple row fields.

Example fix

// before
FeastFeatureStoreEnrichmentHandler(..., entity_id='id', entity_row_fn=lambda row: row['id'])
// after
FeastFeatureStoreEnrichmentHandler(..., entity_id='id')

Defensive patterns

Strategy: validation

Validate before calling

assert bool(entity_id) != bool(entity_row_fn), 'provide exactly one of entity_id or entity_row_fn'

Prevention

Choose one convention per pipeline (prefer entity_id for simple columns).
Review constructor kwargs for accidental duplication from config merging.
Write a smoke test that constructs the handler before submission.

When it happens

Trigger: Constructing `FeastFeatureStoreEnrichmentHandler` with both `entity_id='user_id'` and `entity_row_fn=lambda row: ...`, or omitting both parameters entirely.

Common situations: Config merging where two layers each set a different entity option; forgetting the entity parameter when adding the handler to an existing pipeline template.

Related errors

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