deepset-ai/haystack · error · ValueError

Invalid image format: {params['format']}. Valid options are:

Error message

Invalid image format: {params['format']}. Valid options are: {valid_formats}.

What it means

_to_mermaid_image validates mermaid.ink image parameters before rendering a pipeline diagram. Haystack raises this when the 'format' key in params is not one of the supported mermaid.ink output formats. It is an immediate fail-fast input validation error.

Source

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

            - height: Height of the output image (integer).
            - scale: Scaling factor (1–3). Only applicable if 'width' or 'height' is specified.
            - fit: Whether to fit the diagram size to the page (PDF only, boolean).
            - paper: Paper size for PDFs (e.g., 'a4', 'a3'). Ignored if 'fit' is true.
            - landscape: Landscape orientation for PDFs (boolean). Ignored if 'fit' is true.

    :raises ValueError:
        If any parameter is invalid or does not match the expected format.
    """
    valid_img_types = {"jpeg", "png", "webp"}
    valid_themes = {"default", "neutral", "dark", "forest"}
    valid_formats = {"img", "svg", "pdf"}

    params.setdefault("format", "img")
    params.setdefault("type", "png")
    params.setdefault("theme", "neutral")

    if params["format"] not in valid_formats:
        raise ValueError(f"Invalid image format: {params['format']}. Valid options are: {valid_formats}.")

    if params["format"] == "img" and params["type"] not in valid_img_types:
        raise ValueError(f"Invalid image type: {params['type']}. Valid options are: {valid_img_types}.")

    if params["theme"] not in valid_themes:
        raise ValueError(f"Invalid theme: {params['theme']}. Valid options are: {valid_themes}.")

    if "width" in params and not isinstance(params["width"], int):
        raise ValueError("Width must be an integer.")
    if "height" in params and not isinstance(params["height"], int):
        raise ValueError("Height must be an integer.")

    if "scale" in params and not 1 <= params["scale"] <= 3:
        raise ValueError("Scale must be a number between 1 and 3.")
    if "scale" in params and not ("width" in params or "height" in params):
        raise ValueError("Scale is only allowed when width or height is set.")

    if "bgColor" in params and not isinstance(params["bgColor"], str):

View on GitHub (pinned to e318778c9b)

Solutions

1. Set params['format'] to one of the valid formats listed in the error message (e.g. 'img', 'svg', 'pdf')
2. Remove the 'format' key entirely and let it default to 'img'
3. If you meant a raster type, keep format='img' and set type='png' or 'jpeg'

Example fix

// before
pipeline.draw(path="graph.png", params={"format": "png"})  # ValueError
// after
pipeline.draw(path="graph.png", params={"format": "img", "type": "png"})

VALID = {"img", "svg", "pdf"}
if params.get("format", "img") not in VALID:
    raise ValueError(f"format must be one of {sorted(VALID)}")

def has_valid_format(params: dict) -> bool:
    return params.get("format", "img") in {"img", "svg", "pdf"}

try:
    pipeline.draw(path, params=params)
except ValueError as e:
    logger.error("draw params rejected: %s", e)

When it happens

Trigger: Calling pipeline.draw(path, image_type="mermaid-image"-style flow) with params={'format': 'jpeg'} or any format outside the valid list (e.g. 'png', 'jpg' misspellings) instead of a supported value such as 'img', 'svg', 'pdf'.

Common situations: Copying mermaid CLI options (which differ from mermaid.ink query params) into haystack draw params; typos like 'png' passed as format when it belongs in 'type'.

Related errors

• Invalid image type: {params['type']}. Valid options are: {va
• Invalid theme: {params['theme']}. Valid options are: {valid_
• Width must be an integer.
• Height must be an integer.
• Scale must be a number between 1 and 3.

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