deepset-ai/haystack · error · TypeError

The 'pipeline' parameter must be an instance of Pipeline. Go

Error message

The 'pipeline' parameter must be an instance of Pipeline. Got {type(pipeline)} instead.

What it means

PipelineTool.__init__ validates that the 'pipeline' argument is an actual haystack Pipeline instance before wrapping it in a SuperComponent. Passing anything else (a dict of pipeline data, None, a serialized pipeline, or another object) raises TypeError immediately.

Source

Thrown at haystack/tools/pipeline_tool.py:186

            Optional dictionary defining how tool outputs map to keys within state as well as optional handlers.
            If the source is provided only the specified output key is sent to the handler.
            Example:
            ```python
            {
                "documents": {"source": "docs", "handler": custom_handler}
            }
            ```
            If the source is omitted the whole tool result is sent to the handler.
            Example:
            ```python
            {
                "documents": {"handler": custom_handler}
            }
            ```
        :raises ValueError: If the provided pipeline is not a valid Haystack Pipeline instance.
        """
        if not isinstance(pipeline, Pipeline):
            raise TypeError(f"The 'pipeline' parameter must be an instance of Pipeline. Got {type(pipeline)} instead.")

        super().__init__(
            component=SuperComponent(pipeline=pipeline, input_mapping=input_mapping, output_mapping=output_mapping),
            name=name,
            description=description,
            parameters=parameters,
            outputs_to_string=outputs_to_string,
            inputs_from_state=inputs_from_state,
            outputs_to_state=outputs_to_state,
        )
        self._unresolved_parameters = parameters
        self._pipeline = pipeline
        self._input_mapping = input_mapping
        self._output_mapping = output_mapping

    def to_dict(self) -> dict[str, Any]:
        """
        Serializes the PipelineTool to a dictionary.

View on GitHub (pinned to e318778c9b)

Solutions

Pass an instantiated Pipeline: PipelineTool(pipeline=Pipeline.loads(yaml_str))
If you have a dict, reconstruct with Pipeline.from_dict(data) before passing
Add isinstance(pipeline, Pipeline) check at call site before constructing PipelineTool

Example fix

// before
pipeline_tool = PipelineTool(pipeline=pipeline_dict)

// after
from haystack import Pipeline
pipeline_tool = PipelineTool(pipeline=Pipeline.from_dict(pipeline_dict))

Defensive patterns

Strategy: type-guard

Validate before calling

from haystack import Pipeline

def build_pipeline_tool(pipeline, **kwargs):
    if not isinstance(pipeline, Pipeline):
        raise TypeError(f"Expected Pipeline, got {type(pipeline).__name__}; use Pipeline.from_dict/loads")
    return PipelineTool(pipeline=pipeline, **kwargs)

Type guard

def is_pipeline(obj) -> bool:
    from haystack import Pipeline
    return isinstance(obj, Pipeline)

Try / catch

try:
    pt = PipelineTool(pipeline=pipeline)
except TypeError as e:
    logger.error("pipeline arg invalid: %s", e)
    pipeline = Pipeline.loads(pipeline_yaml)
    pt = PipelineTool(pipeline=pipeline)

Prevention

Never pass serialized pipeline dicts/YAML directly — reconstruct with Pipeline.from_dict / Pipeline.loads first
Add an isinstance(pipeline, Pipeline) assertion at the boundary where pipelines are loaded
Keep variable names distinct for pipeline config data vs the Pipeline instance

When it happens

Trigger: PipelineTool(pipeline=<not-a-Pipeline>) — e.g. passing the result of Pipeline.dumps()/to_dict(), a YAML string, None, or a component instead of a Pipeline.

Common situations: Loading pipelines from YAML/JSON and forgetting to call Pipeline.loads()/from_dict(); variable shadowing where 'pipeline' holds config data; passing a PipelineTool or component where a Pipeline is expected.

Understand the failure class

Background: "Wrong argument type", "must be a string", "expected Array or Prism::Scope": TypeError and ArgumentError when a library receives a value of the wrong type — this error's family across 28 libraries.

Related errors

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/5f5b93f204ee046b. Report an issue: GitHub.