apache/beam · error · ValueError

gcp dependencies not installed. Cannot use

Error message

gcp dependencies not installed. Cannot use {enrichment_handler} handler. Please install using 'pip install apache-beam[gcp]'.

What it means

enrichment_transform in apache_beam.yaml.yaml_enrichment raises ValueError when the Enrichment transform is used but the apache-beam[gcp] extra isn't installed, so the Enrichment module (and handlers like FeastFeatureStore) couldn't be imported. The handler therefore cannot run.

Solutions

1. Install the extra: pip install 'apache-beam[gcp]'.
2. Rebuild/pin the runner container image to include the GCP extra dependencies.
3. Add the dependency to requirements.txt/setup.py used by Dataflow so workers install it at launch.

Example fix

// before
pip install apache-beam
// after
pip install 'apache-beam[gcp]'

try:
    from apache_beam.transforms.enrichment import Enrichment
    gcp_ok = True
except ImportError:
    gcp_ok = False
if not gcp_ok:
    raise SystemExit("Install GCP extra: pip install 'apache-beam[gcp]'")

def gcp_extra_installed() -> bool:
    import importlib.util
    return importlib.util.find_spec('apache_beam.transforms.enrichment') is not None

try:
    enrichment_transform(pcoll, enrichment_handler=handler, ...)
except ValueError as e:
    if 'gcp dependencies not installed' in str(e):
        raise SystemExit("Run: pip install 'apache-beam[gcp]' and redeploy") from e
    raise

When it happens

Trigger: YAML pipeline uses Enrichment with a GCP-backed handler (e.g. VertexAIFeatureStore, FeastFeatureStore) while apache_beam.yaml.yaml_enrichment failed to import Enrichment because google-cloud dependencies are absent.

Common situations: Slim/base Beam installs (no [gcp] extra) deployed to runners; container images without google-cloud-* packages; local venvs created with `pip install apache-beam` instead of `apache-beam[gcp]`.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• GCP dependencies are not installed. Cannot use DicomSearch…
• A VPC network must be provided to use a private endpoint.
• Ambiguous expression type (perhaps missing quoting?)
• Ambiguous expression type (perhaps missing quoting?)
• Append to stream failed with invalid offset of

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

Appendix: source

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

    Args:
        enrichment_handler (str): Specifies the source from where data needs
          to be extracted into the pipeline for enriching data. One of
          "BigQuery", "BigTable", "FeastFeatureStore" or "VertexAIFeatureStore".
        handler_config (str): Specifies the parameters for the respective
          enrichment_handler in a YAML/JSON format. To see the full set of
          handler_config parameters, see their corresponding doc pages:

            - [BigQueryEnrichmentHandler](https://beam.apache.org/releases/pydoc/current/apache_beam.transforms.enrichment_handlers.bigquery.html#apache_beam.transforms.enrichment_handlers.bigquery.BigQueryEnrichmentHandler)
            - [BigTableEnrichmentHandler](https://beam.apache.org/releases/pydoc/current/apache_beam.transforms.enrichment_handlers.bigtable.html#apache_beam.transforms.enrichment_handlers.bigtable.BigTableEnrichmentHandler)
            - [FeastFeatureStoreEnrichmentHandler](https://beam.apache.org/releases/pydoc/current/apache_beam.transforms.enrichment_handlers.feast_feature_store.html#apache_beam.transforms.enrichment_handlers.feast_feature_store.FeastFeatureStoreEnrichmentHandler)
            - [VertexAIFeatureStoreEnrichmentHandler](https://beam.apache.org/releases/pydoc/current/apache_beam.transforms.enrichment_handlers.vertex_ai_feature_store.html#apache_beam.transforms.enrichment_handlers.vertex_ai_feature_store.VertexAIFeatureStoreEnrichmentHandler)
        timeout (float): Timeout for source requests in seconds. Defaults to 30
          seconds.
    """
  options.YamlOptions.check_enabled(pcoll.pipeline, 'Enrichment')

  if not Enrichment:
    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}")

View on GitHub (pinned to 12126d8942)