{"record":{"id":"74b23913e616cbbd","repo":"apache/beam","slug":"unexpected-pipeline-runner-s-valid-values-are-s-or-the-fully","errorCode":null,"errorMessage":"Unexpected pipeline runner: %s. Valid values are %s or the fully qualified name of a PipelineRunner subclass.","messagePattern":"Unexpected pipeline runner: (.+?)\\. Valid values are (.+?) or the fully qualified name of a PipelineRunner subclass\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/runners/runner.py","lineNumber":97,"sourceCode":"      _RUNNER_MAP.get(runner_name.lower() + 'runner', runner_name))\n\n  if '.' in runner_name:\n    module, runner = runner_name.rsplit('.', 1)\n    try:\n      return getattr(importlib.import_module(module), runner)()\n    except ImportError:\n      if 'dataflow' in runner_name.lower():\n        raise ImportError(\n            'Google Cloud Dataflow runner not available, '\n            'please install apache_beam[gcp]')\n      elif 'interactive' in runner_name.lower():\n        raise ImportError(\n            'Interactive runner not available, '\n            'please install apache_beam[interactive]')\n      else:\n        raise\n  else:\n    raise ValueError(\n        'Unexpected pipeline runner: %s. Valid values are %s '\n        'or the fully qualified name of a PipelineRunner subclass.' %\n        (runner_name, ', '.join(StandardOptions.KNOWN_RUNNER_NAMES)))\n\n\nclass PipelineRunner(object):\n  \"\"\"A runner of a pipeline object.\n\n  The base runner provides a run() method for visiting every node in the\n  pipeline's DAG and executing the transforms computing the PValue in the node.\n\n  A custom runner will typically provide implementations for some of the\n  transform methods (ParDo, GroupByKey, Create, etc.). It may also\n  provide a new implementation for clear_pvalue(), which is used to wipe out\n  materialized values in order to reduce footprint.\n  \"\"\"\n  def run(\n      self,","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/runners/runner.py#L79-L115","documentation":"create_runner() only accepts known runner names (StandardOptions.KNOWN_RUNNER_NAMES) or a fully qualified PipelineRunner subclass name. Any other string reaches the else branch and raises this ValueError listing the valid values.","triggerScenarios":"Calling create_runner() with an unrecognized runner_name string, e.g. create_runner('myrunner') or a typo like 'DirectRuner'; no ImportError occurred, the name simply failed to match known runners or a resolvable qualified class path.","commonSituations":"Typo in runner name from CLI flags or config files; passing a class object instead of its fully qualified string; older/newer Beam versions where the runner name is not in KNOWN_RUNNER_NAMES.","solutions":["Use one of the valid names printed in the error (e.g. DirectRunner, DataflowRunner, FlinkRunner, SparkRunner)","Pass the fully qualified class name of a custom PipelineRunner subclass, e.g. 'mypkg.runners.MyRunner'","Check for typos and case in the runner name coming from flags/config"],"exampleFix":"// before\nrunner = create_runner('DirectRuner')\n// after\nrunner = create_runner('DirectRunner')","handlingStrategy":"validation","validationCode":"from apache_beam.options.pipeline_options import StandardOptions\nVALID = set(StandardOptions.KNOWN_RUNNER_NAMES)\nassert runner_name in VALID or '.' in runner_name, f'unknown runner: {runner_name}'","typeGuard":null,"tryCatchPattern":"try:\n    runner = create_runner(name)\nexcept ValueError as e:\n    print(e)  # lists valid values\n    runner = create_runner('DirectRunner')","preventionTips":["Copy runner names from StandardOptions.KNOWN_RUNNER_NAMES instead of typing them","Keep runner name in one config constant","For custom runners, pass the fully qualified class name string"],"tags":["apache-beam","python","invalid-argument-value","runner"],"backgroundTag":"invalid-argument-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"}