apache/beam · error · ValueError

unsupported because is not set in…

Error message

{description or feature} unsupported because {feature} is not set in --yaml_experimental_features option.

What it means

check_enabled in apache_beam.yaml.options raises ValueError when a YAML feature gated behind --yaml_experimental_features is used without opting in. Experimental features must be explicitly enabled per pipeline run via the option list.

Solutions

1. Add the feature to the pipeline options: --yaml_experimental_features=<FeatureName> (comma-separated for several).
2. In Python API, set the option via PipelineOptions flags: ['--yaml_experimental_features=Enrichment'].
3. Check the feature's documentation for the exact option string expected by check_enabled.

Example fix

// before
python -m apache_beam.yaml.main --yaml_pipeline_file p.yaml
// after
python -m apache_beam.yaml.main --yaml_pipeline_file p.yaml --yaml_experimental_features=Enrichment

def ensure_feature(flags: list, feature: str):
    opts = [f.split('=', 1)[1] for f in flags if f.startswith('--yaml_experimental_features=')]
    enabled = {name for chunk in opts for name in chunk.split(',')}
    if feature not in enabled:
        raise SystemExit(f'Add --yaml_experimental_features={feature}')

def feature_enabled(pipeline, feature: str) -> bool:
    from apache_beam.yaml import options
    return feature in pipeline._options.view_as(options.YamlOptions).yaml_experimental_features

try:
    enrichment_transform(pcoll, ...)
except ValueError as e:
    if 'yaml_experimental_features' in str(e):
        rebuild_pipeline_with_feature_flag(extract_feature_name(str(e)))
    else:
        raise

When it happens

Trigger: Invoking a feature that calls YamlOptions.check_enabled(pipeline, 'FeatureName') while the pipeline options do not include that feature name in yaml_experimental_features (e.g. Enrichment, SQL experimental paths).

Common situations: Users deploy a YAML pipeline using an experimental transform (e.g. Enrichment) locally then to Dataflow without adding --yaml_experimental_features=Enrichment; upgrading Beam picks up a newly gated feature.

Related errors

• Ambiguous expression type (perhaps missing quoting?)
• Ambiguous expression type (perhaps missing quoting?)
• Can only use expressions on a schema'd input.
• CombineFn spec missing type
• Config for transform at

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

Appendix: source

Thrown at sdks/python/apache_beam/yaml/options.py:34

#

from apache_beam.options import pipeline_options


class YamlOptions(pipeline_options.PipelineOptions):
  @classmethod
  def _add_argparse_args(cls, parser):
    parser.add_argument(
        '--yaml_experimental_features',
        dest='yaml_experimental_features',
        action='append',
        default=[],
        help=('Enable yaml features ahead of them being declared stable.'))

  @classmethod
  def check_enabled(cls, pipeline, feature, description=None):
    if feature not in pipeline._options.view_as(cls).yaml_experimental_features:
      raise ValueError(
          f'{description or feature} unsupported because '
          f'{feature} is not set in --yaml_experimental_features option.')

View on GitHub (pinned to 12126d8942)