apache/beam · error · ValueError

Unknown enrichment source: {enrichment_handler}

Error message

Unknown enrichment source: {enrichment_handler}

What it means

enrichment_transform looks up the handler name in a fixed handler_map of known enrichment sources (BigQuery, BigTable, FeastFeatureStore, VertexAIFeatureStore). If the requested enrichment_handler is not one of these keys, the transform raises ValueError listing nothing else valid, because enrichment only supports these built-in sources.

Source

Thrown at sdks/python/apache_beam/yaml/yaml_enrichment.py:105

    raise ValueError(
        f"gcp dependencies not installed. Cannot use {enrichment_handler} "
        f"handler. Please install using 'pip install apache-beam[gcp]'.")

  if (enrichment_handler == 'FeastFeatureStore' and
      not FeastFeatureStoreEnrichmentHandler):
    raise ValueError(
        "FeastFeatureStore handler requires 'feast' package to be installed. " +
        "Please install using 'pip install feast[gcp]' and try again.")

  handler_map = {
      'BigQuery': BigQueryEnrichmentHandler,
      'BigTable': BigTableEnrichmentHandler,
      'FeastFeatureStore': FeastFeatureStoreEnrichmentHandler,
      'VertexAIFeatureStore': VertexAIFeatureStoreEnrichmentHandler
  }

  if enrichment_handler not in handler_map:
    raise ValueError(f"Unknown enrichment source: {enrichment_handler}")

  handler = handler_map[enrichment_handler](**handler_config)
  return pcoll | Enrichment(source_handler=handler, timeout=timeout)

View on GitHub (pinned to 12126d8942)

Solutions

1. Use exactly one of: 'BigQuery', 'BigTable', 'FeastFeatureStore', 'VertexAIFeatureStore' (case-sensitive).
2. Fix casing/typos in the handler name in the YAML transform config.
3. If a custom source is needed, implement it via the Enrichment transform directly in Python rather than the YAML wrapper.

Example fix

// before
- type: Enrichment
  source: bigquery
// after
- type: Enrichment
  source: BigQuery

VALID = {'BigQuery', 'BigTable', 'FeastFeatureStore', 'VertexAIFeatureStore'}
assert handler in VALID, f"Unknown enrichment source: {handler}; expected one of {sorted(VALID)}"

try:
    enrichment_transform(pcoll, handler, config)
except ValueError as e:
    if str(e).startswith('Unknown enrichment source'):
        log_valid_handlers({'BigQuery','BigTable','FeastFeatureStore','VertexAIFeatureStore'})

When it happens

Trigger: Calling enrichment_transform with enrichment_handler set to any string not in handler_map, e.g. a typo like 'Bigquery', 'bigquery', or an unsupported source like 'RedisFeatureStore'.

Common situations: Typos or wrong casing in the YAML 'handler'/'source' field; copying a handler name from another framework; assuming arbitrary feature stores are supported.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown format: {format}
• Unknown ML transform type: %r
• f'Unknown parameters {spec.keys()}'
• "Cannot specify 'callable' with 'path' and 'name' for functi
• Missing type parameter for transform at {identify_object(spe

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