deepset-ai/haystack · error · PipelineDrawingError

This method is only supported in Jupyter notebooks. Use Pipe

Error message

This method is only supported in Jupyter notebooks. Use Pipeline.draw() to save an image locally.

What it means

Pipeline.show() raises PipelineDrawingError when called outside a Jupyter notebook. show() renders the pipeline image inline via IPython's display(); outside Jupyter there is no display hook, so you must use Pipeline.draw(path=...) to save the image to a file instead.

Source

Thrown at haystack/core/pipeline/base.py:961

            from IPython.display import Image, display

            if super_component_expansion:
                graph, super_component_mapping = self._merge_super_component_pipelines()
            else:
                graph = self.graph
                super_component_mapping = None

            image_data = _to_mermaid_image(
                graph,
                server_url=server_url,
                params=params,
                timeout=timeout,
                super_component_mapping=super_component_mapping,
            )
            display(Image(image_data))
        else:
            msg = "This method is only supported in Jupyter notebooks. Use Pipeline.draw() to save an image locally."
            raise PipelineDrawingError(msg)

    def draw(
        self,
        *,
        path: Path,
        server_url: str = "https://mermaid.ink",
        params: dict | None = None,
        timeout: int = 30,
        super_component_expansion: bool = False,
    ) -> None:
        """
        Save an image representing this `Pipeline` to the specified file path.

        This function generates a diagram of the `Pipeline` using the Mermaid server and saves it to the provided path.

        :param path:
            The file path where the generated image will be saved.

View on GitHub (pinned to e318778c9b)

Solutions

Replace show() with pipeline.draw(path='pipeline.png') to save to a file
If in Jupyter, ensure IPython is installed and the kernel is running so get_ipython() returns a shell
In scripts, open the saved image after draw() if you need to view it

Example fix

// before
pipeline.show()  # in a script
// after
pipeline.draw(path='pipeline.png')

Defensive patterns

Strategy: fallback

Validate before calling

def in_jupyter() -> bool:
    try:
        return get_ipython() is not None  # noqa: F821
    except NameError:
        return False
assert in_jupyter(), 'Use pipeline.draw(path=...) outside Jupyter'

Type guard

def supports_show() -> bool:
    try:
        import ipykernel  # noqa: F401
        return get_ipython() is not None  # noqa: F821
    except Exception:
        return False

Try / catch

try:
    pipeline.show()
except PipelineDrawingError:
    pipeline.draw(path='pipeline.png')

Prevention

Use draw(path=...) in scripts, services and CI
Reserve show() for interactive notebooks
Gate show() behind an is-notebook check in shared utilities

When it happens

Trigger: Calling pipeline.show() in a plain Python script, REPL, or web backend; running in Jupyter without IPython display available (get_ipython() returns None).

Common situations: Porting notebook code into a script or service; CI pipelines running notebook logic headlessly; missing IPython installation in the environment.

Related errors

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