deepset-ai/haystack · error · ValueError

Scale must be a number between 1 and 3.

Error message

Scale must be a number between 1 and 3.

What it means

The mermaid 'scale' parameter is only valid within 1..3 (inclusive). Haystack raises this when params['scale'] is outside that range or not a number.

Source

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

    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):
            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`.")

View on GitHub (pinned to e318778c9b)

Solutions

  1. Clamp scale into range: params['scale'] = max(1, min(3, int(params['scale'])))
  2. Use width/height for larger outputs instead of scale
  3. Remove 'scale' if not supported by your target format

Example fix

// before
pipeline.draw(path="g.png", params={"width": 1600, "scale": 5})  # ValueError
// after
pipeline.draw(path="g.png", params={"width": 3200})
Defensive patterns

Strategy: validation

Validate before calling

if "scale" in params and not 1 <= params["scale"] <= 3:
    params["scale"] = max(1, min(3, params["scale"]))

Type guard

def valid_scale(params: dict) -> bool:
    return "scale" not in params or (isinstance(params["scale"], (int, float)) and 1 <= params["scale"] <= 3)

Try / catch

try:
    pipeline.draw(path, params=params)
except ValueError as e:
    if "Scale" in str(e):
        params.pop("scale", None)
        pipeline.draw(path, params=params)

Prevention

When it happens

Trigger: params={'scale': 0}, {'scale': 5}, or a non-numeric string like '2x'.

Common situations: Users expecting CLI-style zoom factors (>3) or fractional scaling; misreading scale as a percentage.

Related errors

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