deepset-ai/haystack · error · ValueError

Width must be an integer.

Error message

Width must be an integer.

What it means

Width for mermaid image rendering must be an integer (pixels). Haystack raises this when params['width'] is present but is not an int.

Source

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

    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):
        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):

View on GitHub (pinned to e318778c9b)

Solutions

1. Cast the value: params['width'] = int(params['width']) before calling draw
2. Pass a plain int literal instead of a string/float
3. Remove 'width' if scaling is handled elsewhere

Example fix

// before
pipeline.draw(path="g.png", params={"width": "800"})  # ValueError
// after
pipeline.draw(path="g.png", params={"width": int("800")})

if "width" in params and (not isinstance(params["width"], int) or isinstance(params["width"], bool)):
    params["width"] = int(params["width"])

def is_int_width(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool)

try:
    pipeline.draw(path, params=params)
except ValueError as e:
    if "Width must be an integer" in str(e):
        params["width"] = int(params["width"])
        pipeline.draw(path, params=params)

When it happens

Trigger: Passing params={'width': '800'} (string from CLI/env), {'width': 800.0} (float), or {'width': None}.

Common situations: Reading dimensions from config files or CLI args where everything is a string; JSON numbers decoded oddly.

Related errors

• Height must be an integer.
• Background color must be a string.
• Fit must be a boolean.
• Invalid image format: {params['format']}. Valid options are:
• Invalid image type: {params['type']}. Valid options are: {va

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