{"record":{"id":"409b6ec3cab6b1ac","repo":"apache/beam","slug":"exactly-one-of-yaml-pipeline-or-yaml-pipeline-file-must-be","errorCode":null,"errorMessage":"Exactly one of yaml_pipeline or yaml_pipeline_file must be set.","messagePattern":"Exactly one of yaml_pipeline or yaml_pipeline_file must be set\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/yaml/main.py","lineNumber":140,"sourceCode":"      'Requires --test_suite if the pipeline uses jinja formatting.')\n  parser.add_argument(\n      '--create_test',\n      action=argparse.BooleanOptionalAction,\n      help='Automatically creates a regression test for the given pipeline, '\n      'adding it to the pipeline spec or test suite dependon on whether '\n      '--test_suite is given. '\n      'Requires --test_suite if the pipeline uses jinja formatting.')\n  parser.add_argument(\n      '--test_suite',\n      help='Run the given tests against the given pipeline, rather than the '\n      'pipeline itself. '\n      'Should be a file containing a list of yaml test specifications.')\n  return parser.parse_known_args(argv)\n\n\ndef _pipeline_spec_from_args(known_args):\n  if known_args.yaml_pipeline_file and known_args.yaml_pipeline:\n    raise ValueError(\n        \"Exactly one of yaml_pipeline or yaml_pipeline_file must be set.\")\n  elif known_args.yaml_pipeline_file:\n    with FileSystems.open(known_args.yaml_pipeline_file) as fin:\n      pipeline_yaml = fin.read().decode()\n  elif known_args.yaml_pipeline:\n    pipeline_yaml = known_args.yaml_pipeline\n  else:\n    raise ValueError(\n        \"Exactly one of yaml_pipeline or yaml_pipeline_file must be set.\")\n\n  return pipeline_yaml\n\n\ndef run(argv=None):\n  options, constructor, display_data = build_pipeline_components_from_argv(argv)\n  with beam.Pipeline(options=options, display_data=display_data) as p:\n    print('Building pipeline...')\n    constructor(p)","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/yaml/main.py#L122-L158","documentation":"Pipeline specification in apache_beam.yaml.main accepts the pipeline either inline via --yaml_pipeline or from a file via --yaml_pipeline_file, but not both. Supplying both is ambiguous, so _pipeline_spec_from_args raises this ValueError.","triggerScenarios":"Running `python -m apache_beam.yaml.main --yaml_pipeline <yaml> --yaml_pipeline_file <path>` (or _build_pipeline_yaml_from_argv with both argv flags populated).","commonSituations":"Shell scripts with a default --yaml_pipeline flag plus an explicitly passed --yaml_pipeline_file; CI configs merging multiple sources of the pipeline definition; copy-pasted command lines accumulating both flags.","solutions":["Remove --yaml_pipeline from the command and keep only --yaml_pipeline_file (or vice versa).","If both sources exist in a script, pick one programmatically before invoking: use the file when present, else the inline string.","Check environment-variable-driven flag assembly (e.g. ${YAML_PIPELINE:+--yaml_pipeline ...}) so only one flag is ever emitted.","Wrap the invocation and catch ValueError to give a clearer CLI error message to users."],"exampleFix":"# before\npython -m apache_beam.yaml.main --yaml_pipeline \"$(cat p.yaml)\" --yaml_pipeline_file p.yaml\n# after\npython -m apache_beam.yaml.main --yaml_pipeline_file p.yaml","handlingStrategy":"validation","validationCode":"import sys\nflags = sys.argv\nhas_inline = '--yaml_pipeline' in flags\nhas_file = '--yaml_pipeline_file' in flags\nassert not (has_inline and has_file), 'pass only one of --yaml_pipeline / --yaml_pipeline_file'","typeGuard":"def has_conflicting_pipeline_sources(argv):\n    return '--yaml_pipeline' in argv and '--yaml_pipeline_file' in argv","tryCatchPattern":"try:\n    apache_beam.yaml.main.run(argv)\nexcept ValueError as e:\n    if 'Exactly one of yaml_pipeline' in str(e):\n        parser.error('--yaml_pipeline and --yaml_pipeline_file are mutually exclusive')\n    raise","preventionTips":["Prefer --yaml_pipeline_file in scripts; use inline YAML only for ad-hoc runs.","Never template both flags into a shared command builder.","Audit shell scripts for hardcoded --yaml_pipeline defaults that conflict with user flags."],"tags":["python","apache-beam","yaml","cli","conflicting-flags"],"backgroundTag":"mutually-exclusive-flags","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}