{"record":{"id":"b33bf2e32d096b82","repo":"apache/beam","slug":"unknown-or-inapplicable-phase-for-pre-optimize-s","errorCode":null,"errorMessage":"Unknown or inapplicable phase for pre_optimize: %s","messagePattern":"Unknown or inapplicable phase for pre_optimize: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/runners/dataflow/dataflow_runner.py","lineNumber":480,"sourceCode":"\n    # Optimize the pipeline if it not streaming and the pre_optimize\n    # experiment is set.\n    if not options.view_as(StandardOptions).streaming:\n      pre_optimize = options.view_as(DebugOptions).lookup_experiment(\n          'pre_optimize', 'default').lower()\n      from apache_beam.runners.portability.fn_api_runner import translations\n      if pre_optimize == 'none':\n        phases = []\n      elif pre_optimize == 'default' or pre_optimize == 'all':\n        phases = [translations.pack_combiners, translations.sort_stages]\n      else:\n        phases = []\n        for phase_name in pre_optimize.split(','):\n          # For now, these are all we allow.\n          if phase_name in ('pack_combiners', ):\n            phases.append(getattr(translations, phase_name))\n          else:\n            raise ValueError(\n                'Unknown or inapplicable phase for pre_optimize: %s' %\n                phase_name)\n        phases.append(translations.sort_stages)\n\n      if phases:\n        self.proto_pipeline = translations.optimize_pipeline(\n            self.proto_pipeline,\n            phases=phases,\n            known_runner_urns=frozenset(),\n            partial=True)\n\n    # Add setup_options for all the BeamPlugin imports\n    setup_options = options.view_as(SetupOptions)\n    plugins = BeamPlugin.get_all_plugin_paths()\n    if setup_options.beam_plugins is not None:\n      plugins = list(set(plugins + setup_options.beam_plugins))\n    setup_options.beam_plugins = plugins\n","sourceCodeStart":462,"sourceCodeEnd":498,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/runners/dataflow/dataflow_runner.py#L462-L498","documentation":"The --pre_optimize option lets users run pipeline-optimization translations before submitting to Dataflow, but only a whitelisted set of phases is applicable on this runner path. Passing any other phase name raises this ValueError listing the offending phase.","triggerScenarios":"Setting pipeline option pre_optimize to a comma-separated list containing anything other than 'pack_combiners' (e.g. pre_optimize=all or pre_optimize=sort_stages) when using the Dataflow non-portable path.","commonSituations":"Copying --pre_optimize flags from documentation for a different runner; assuming all translations.* phases are valid pre_optimize phases.","solutions":["Change pre_optimize to only use supported phases, e.g. --pre_optimize=pack_combiners.","Remove the pre_optimize option entirely to use the default optimization behavior.","Check apache_beam/runners/transform.py translations for phases supported by your Beam version.","Upgrade apache-beam if a newer version whitelists the phase you need."],"exampleFix":"// before\n--pre_optimize=all\n// after\n--pre_optimize=pack_combiners","handlingStrategy":"validation","validationCode":"SUPPORTED = {'pack_combiners'}\nphases = [p for p in opts.pre_optimize.split(',') if p]\nassert all(p in SUPPORTED for p in phases), f'unsupported pre_optimize: {phases}'","typeGuard":null,"tryCatchPattern":"try:\n    pipeline.run()\nexcept ValueError as e:\n    if 'pre_optimize' in str(e):\n        opts.view_as(SetupOptions).pre_optimize = 'pack_combiners'\n        pipeline.run()","preventionTips":["Only pass --pre_optimize=pack_combiners on the Dataflow non-portable path","Validate pre_optimize values in wrapper scripts before submit","Drop pre_optimize unless you specifically need packed combiners"],"tags":["python","apache-beam","dataflow","cli-argument","pipeline-options"],"backgroundTag":"invalid-enum-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}