apache/beam · error · TypeError

pipeline should either be a %s or %s, while %s is given

Error message

pipeline should either be a %s or %s, while %s is given

What it means

PipelineGraph.__init__ accepts either a runner-API Pipeline proto or an apache_beam.Pipeline object; anything else is rejected with this TypeError. It exists to fail fast when an incompatible pipeline representation is passed to interactive graph visualization.

Source

Thrown at sdks/python/apache_beam/runners/interactive/display/pipeline_graph.py:87

      render_option: (str) this parameter decides how the pipeline graph is
          rendered. See display.pipeline_graph_renderer for available options.
    """
    self._lock = threading.Lock()
    self._graph: pydot.Dot = None
    self._pipeline_instrument = None
    if isinstance(pipeline, beam.Pipeline):
      self._pipeline_instrument = inst.PipelineInstrument(
          pipeline, pipeline._options)
      # The pre-process links user pipeline to runner pipeline through analysis
      # but without mutating runner pipeline.
      self._pipeline_instrument.preprocess()

    if isinstance(pipeline, beam_runner_api_pb2.Pipeline):
      self._pipeline_proto = pipeline
    elif isinstance(pipeline, beam.Pipeline):
      self._pipeline_proto = pipeline.to_runner_api()
    else:
      raise TypeError(
          'pipeline should either be a %s or %s, while %s is given' %
          (beam_runner_api_pb2.Pipeline, beam.Pipeline, type(pipeline)))

    # A dict from PCollection ID to a list of its consuming Transform IDs
    self._consumers: collections.defaultdict[
        str, list[str]] = collections.defaultdict(list)
    # A dict from PCollection ID to its producing Transform ID
    self._producers: dict[str, str] = {}

    for transform_id, transform_proto in self._top_level_transforms():
      for pcoll_id in transform_proto.inputs.values():
        self._consumers[pcoll_id].append(transform_id)
      for pcoll_id in transform_proto.outputs.values():
        self._producers[pcoll_id] = transform_id

    default_vertex_attrs = default_vertex_attrs or {'shape': 'box'}
    if 'color' not in default_vertex_attrs:
      default_vertex_attrs['color'] = 'blue'

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass an actual apache_beam.Pipeline instance or a beam_runner_api_pb2.Pipeline proto.
2. If you have a serialized pipeline, deserialize it back to beam_runner_api_pb2.Pipeline (proto ParseFromString) before passing.
3. If you have a dict, convert it with beam_runner_api_pb2.Pipeline(**d) or via json_format.ParseDict.
4. Check apache_beam version consistency if the object comes from another environment.

Example fix

// before
graph = PipelineGraph(pipeline=pipeline.to_runner_api().SerializeToString())
// after
proto = pipeline.to_runner_api()  # beam_runner_api_pb2.Pipeline
graph = PipelineGraph(pipeline=proto)

assert isinstance(pipeline, (beam.Pipeline, beam_runner_api_pb2.Pipeline)), type(pipeline)

def is_valid_pipeline(p) -> bool:
    import apache_beam as beam
    from apache_beam.pipeline import beam_runner_api_pb2
    return isinstance(p, (beam_runner_api_pb2.Pipeline, beam.Pipeline))

try:
    graph = PipelineGraph(pipeline=pipeline)
except TypeError:
    graph = PipelineGraph(pipeline=pipeline.to_runner_api() if hasattr(pipeline, 'to_runner_api') else beam_runner_api_pb2.Pipeline())

When it happens

Trigger: Constructing PipelineGraph(pipeline=...) with e.g. a str, dict, a proto from a different Beam version, a scio/other runner's object, or None instead of a beam.Pipeline or beam_runner_api_pb2.Pipeline.

Common situations: Building custom interactive visualizations and passing a pickled/serialized pipeline string; passing a pipeline from a mismatched apache_beam version whose to_runner_api() output type differs; passing the result of pipeline.to_runner_api() after it was JSON-converted to a dict.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• A cluster_identifier should be Optional[Union[str, beam.Pipe
• {pcoll} is not an apache_beam.pvalue.PCollection.
• Unable to convert objects of type %s to a PCollection
• Encountered unknown type {other!r}
• Proxy '{proxy}' has unsupported type '{type(proxy)}'

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