What causes "Paper size must be a string (e.g., 'a4', 'a3')." in deepset-ai/haystack?

Ensure params['paper'] is a single string like 'a4' or 'a3'

deepset-ai/haystack · error · ValueError

Paper size must be a string (e.g., 'a4', 'a3').

Error message

Paper size must be a string (e.g., 'a4', 'a3').

What it means

Haystack validates Mermaid.ink query parameters before rendering a pipeline diagram. When the output format is 'pdf', the optional 'paper' parameter (page size such as 'a4' or 'a3') must be a string. This ValueError is raised in _validate_mermaid_params when a non-string value (e.g., a list or int) is passed for 'paper'.

Source

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

    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):
        raise ValueError("Background color must be a string.")

    # PDF specific parameters
    if params["format"] == "pdf":
        if "fit" in params and not isinstance(params["fit"], bool):
            raise ValueError("Fit must be a boolean.")
        if "paper" in params and not isinstance(params["paper"], str):
            raise ValueError("Paper size must be a string (e.g., 'a4', 'a3').")
        if "landscape" in params and not isinstance(params["landscape"], bool):
            raise ValueError("Landscape must be a boolean.")
        if "fit" in params and ("paper" in params or "landscape" in params):
            logger.warning("`fit` overrides `paper` and `landscape` for PDFs. Ignoring `paper` and `landscape`.")


# Magic-byte signatures used to verify a Mermaid server response matches the requested output format.
_PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
_JPEG_SIGNATURE = b"\xff\xd8\xff"
_PDF_SIGNATURE = b"%PDF-"
_RIFF_SIGNATURE = b"RIFF"
_WEBP_SIGNATURE = b"WEBP"
_SVG_PREFIXES = (b"<?xml", b"<svg")


def _validate_image_response(resp: httpx.Response, params: dict[str, Any]) -> None:
    """
    Validate that the Mermaid server response actually contains the expected image/SVG/PDF data.

View on GitHub (pinned to e318778c9b)

Solutions

Ensure params['paper'] is a single string like 'a4' or 'a3'
If passing multiple sizes, pick one instead of a list
Validate/normalize the config value with str() before calling draw()

Example fix

// before
params = {"format": "pdf", "paper": ["a4"]}
// after
params = {"format": "pdf", "paper": "a4"}

Defensive patterns

Strategy: validation

Validate before calling

params = {"format": "pdf", "paper": "a4"}
if params.get("format") == "pdf" and "paper" in params and not isinstance(params["paper"], str):
    raise TypeError("paper must be a string, e.g. 'a4'")

Type guard

def is_str(v) -> bool:
    return isinstance(v, str)

Try / catch

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

Prevention

Validate Mermaid params dicts at config load time
Use literals 'a4'/'a3' rather than parsed config values without coercion
Add a small schema check (e.g., pydantic) for draw params

When it happens

Trigger: Calling Pipeline.draw() or show() with a Mermaid config whose format is 'pdf' and paper set to a non-string value, e.g. {'format': 'pdf', 'paper': ['a4']} or paper=4.

Common situations: Users copy JavaScript/CLI examples where paper sizes are arrays, build params programmatically from config files (YAML/JSON) where a paper size list is parsed as a list, or confuse the 'paper' key with the 'format' key.

Related errors

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