deepset-ai/haystack · error · ValueError

Scale is only allowed when width or height is set.

Error message

Scale is only allowed when width or height is set.

What it means

mermaid.ink ignores scale unless explicit width or height is provided; haystack enforces this by raising when 'scale' is set but neither dimension is.

Source

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

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


# Magic-byte signatures used to verify a Mermaid server response matches the requested output format.
_PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"

View on GitHub (pinned to e318778c9b)

Solutions

  1. Add a width or height alongside scale (e.g. {'width': 1024, 'scale': 2})
  2. Drop 'scale' if you don't need it

Example fix

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

Strategy: validation

Validate before calling

if "scale" in params and "width" not in params and "height" not in params:
    params["width"] = params.get("width", 1024)

Type guard

def scale_has_dimension(params: dict) -> bool:
    return "scale" not in params or "width" in params or "height" in params

Try / catch

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

Prevention

When it happens

Trigger: Calling draw with params={'scale': 2} and no 'width'/'height' keys.

Common situations: Users copy a scale option from mermaid CLI docs without realizing haystack requires a dimension for it to take effect.

Related errors

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