apache/beam · error · TypeError

Runner is not a PipelineRunner object or the name of a…

Error message

Runner %s is not a PipelineRunner object or the name of a registered runner.

What it means

Pipeline.__init__ raises TypeError when the `runner` argument is neither a PipelineRunner instance nor a string naming a registered runner. Beam resolves runners either from an object or by looking up a name in the runner registry; anything else cannot be used to execute the pipeline.

Solutions

1. Pass a registered runner name string, e.g. Pipeline(runner='DirectRunner') or 'FlinkRunner'.
2. Pass an instance: Pipeline(runner=DirectRunner()).
3. If using a custom runner, make it subclass apache_beam.runners.pipeline_context/PipelineRunner and register it.
4. Check the variable you're passing isn't the class itself (DirectRunner vs DirectRunner()).

Example fix

// before
pipeline = Pipeline(runner=DirectRunner)
// after
pipeline = Pipeline(runner=DirectRunner())  # or runner='DirectRunner'

def check_runner(runner):
    from apache_beam.pipeline import Pipeline
    from apache_beam.runners.runner import PipelineRunner
    assert isinstance(runner, (str, PipelineRunner)), f'bad runner: {runner}'

def is_valid_runner(r) -> bool:
    from apache_beam.runners.runner import PipelineRunner
    return isinstance(r, PipelineRunner) or (isinstance(r, str) and bool(r))

When it happens

Trigger: Calling Pipeline(runner=SOMETHING) where runner is an arbitrary object (e.g. a class instead of an instance, a misspelled non-registered string that somehow bypassed create_runner, or None-like custom object) and not an instance of PipelineRunner.

Common situations: Passing the runner class (DirectRunner) instead of an instance or string 'DirectRunner'; passing a custom runner object that doesn't subclass PipelineRunner; typos in runner names that fall through custom resolution logic.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• A cluster_identifier should be Optional[Union[str…
• Cannot get a type descriptor for
• Cannot interpret as Duration.
• CombineGlobally can be used only with combineFn objects…
• database_config must be VectorDatabaseWriteConfig, got

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

Appendix: source

Thrown at sdks/python/apache_beam/pipeline.py:208

            argv)
    else:
      self._options = PipelineOptions([])

    FileSystems.set_options(self._options)

    if runner is None:
      runner = self._options.view_as(StandardOptions).runner
      if runner is None:
        runner = StandardOptions.DEFAULT_RUNNER
        logging.info((
            'Missing pipeline option (runner). Executing pipeline '
            'using the default runner: %s.'),
                     runner)

    if isinstance(runner, str):
      runner = create_runner(runner)
    elif not isinstance(runner, PipelineRunner):
      raise TypeError(
          'Runner %s is not a PipelineRunner object or the '
          'name of a registered runner.' % runner)

    # Runner can override the default pickler to be used.
    if (self._options.view_as(SetupOptions).pickle_library == 'default' and
        runner.default_pickle_library_override()):
      logging.info(
          "Runner defaulting to pickling library: %s.",
          runner.default_pickle_library_override())
      self._options.view_as(
          SetupOptions).pickle_library = runner.default_pickle_library_override(
          )
    pickler.set_library(self._options.view_as(SetupOptions).pickle_library)

    # Validate pipeline options
    errors = PipelineOptionsValidator(self._options, runner).validate()
    if errors:
      raise ValueError(

View on GitHub (pinned to 12126d8942)