deepset-ai/haystack · error · PipelineDrawingError

There was an issue with {server_url}, see the stacktrace for

Error message

There was an issue with {server_url}, see the stacktrace for details.

What it means

Any exception during the HTTP request to the Mermaid rendering server (connection errors, timeouts, DNS failures, HTTP error statuses) is caught and re-raised as PipelineDrawingError, with the original exception chained. No diagram is produced.

Source

Thrown at haystack/core/pipeline/draw.py:332

    try:
        resp = httpx.get(url, timeout=timeout)
        if resp.status_code >= 400:
            logger.warning(
                "Failed to draw the pipeline: {server_url} returned status {status_code}",
                server_url=server_url,
                status_code=resp.status_code,
            )
            logger.info("Exact URL requested: {url}", url=url)
            logger.warning("No pipeline diagram will be saved.")
            resp.raise_for_status()

    except Exception as exc:
        logger.warning(
            "Failed to draw the pipeline: could not connect to {server_url} ({error})", server_url=server_url, error=exc
        )
        logger.info("Exact URL requested: {url}", url=url)
        logger.warning("No pipeline diagram will be saved.")
        raise PipelineDrawingError(f"There was an issue with {server_url}, see the stacktrace for details.") from exc

    # Validate the response before it gets written to disk by the caller, so that a misconfigured
    # or malicious server cannot cause arbitrary content to be saved to the output path.
    _validate_image_response(resp, params)

    return resp.content


def _to_mermaid_text(
    graph: networkx.MultiDiGraph, init_params: str | dict, super_component_mapping: dict[str, str] | None = None
) -> str:
    """
    Converts a Networkx graph into Mermaid syntax.

    The output of this function can be used in the documentation with `mermaid` codeblocks and will be
    automatically rendered.

    :param graph: The graph to convert to Mermaid syntax

View on GitHub (pinned to e318778c9b)

Solutions

1. Check network connectivity and that server_url is reachable (curl the base URL)
2. Retry, possibly with a larger 'timeout' in the Mermaid params
3. Use or fix a self-hosted Mermaid renderer if mermaid.ink is blocked/rate-limited
4. Inspect the chained exception (stacktrace) for the root cause

Example fix

// before
pipeline.draw(path="graph.png")  # default server blocked
// after
pipeline.draw(path="graph.png", server_url="http://localhost:3000", params={"timeout": 30})

def can_reach(url: str) -> bool:
    try:
        return requests.get(url, timeout=5).status_code < 500
    except requests.RequestException:
        return False

from haystack.core.errors import PipelineDrawingError
import time
for attempt in range(3):
    try:
        pipeline.draw(path="graph.png")
        break
    except PipelineDrawingError as e:
        logger.warning("draw attempt %d failed: %s", attempt + 1, e)
        time.sleep(2 ** attempt)
else:
    logger.error("Skipping diagram: Mermaid server unavailable")

When it happens

Trigger: Calling Pipeline.draw() or show() when server_url is unreachable, DNS fails, the request times out, or the server returns an HTTP error (e.g., 500/502/429) that raises via resp.raise_for_status().

Common situations: No internet access / offline environment, corporate proxy blocking mermaid.ink, self-hosted renderer down, mermaid.ink rate-limiting or outage, wrong port in server_url.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• The Mermaid server returned an empty response; no image will
• Paper size must be a string (e.g., 'a4', 'a3').
• Landscape must be a boolean.
• The Mermaid server response does not look like a valid {expe
• Invalid format: {endpoint_format}. Valid options are 'img',

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