deepset-ai/haystack · error · ValueError

Background color must be a string.

Error message

Background color must be a string.

What it means

The mermaid background color parameter must be a string (e.g. a hex color or color name). Haystack raises this when params['bgColor'] is any non-string value.

Source

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

    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"
_JPEG_SIGNATURE = b"\xff\xd8\xff"
_PDF_SIGNATURE = b"%PDF-"
_RIFF_SIGNATURE = b"RIFF"

View on GitHub (pinned to e318778c9b)

Solutions

1. Convert to a hex string: params['bgColor'] = f"{value:06X}" if it's an int
2. Use a named color string like 'white' or hex 'FF0000'
3. Remove 'bgColor' to use the default background

Example fix

// before
pipeline.draw(path="g.png", params={"bgColor": 0xFF0000})  # ValueError
// after
pipeline.draw(path="g.png", params={"bgColor": "FF0000"})

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

def is_str_bg(params: dict) -> bool:
    return "bgColor" not in params or isinstance(params["bgColor"], str)

try:
    pipeline.draw(path, params=params)
except ValueError as e:
    if "Background color" in str(e):
        params["bgColor"] = str(params["bgColor"])
        pipeline.draw(path, params=params)

When it happens

Trigger: params={'bgColor': 0xFFFFFF} (int), {'bgColor': ['#fff']} (list), or None.

Common situations: Passing raw RGB integers or tuples from graphics code instead of a hex string like 'FFFFFF' or '!FFFFFF'.

Related errors

• Width must be an integer.
• Height must be an integer.
• 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/2aee3f08575e059f. Report an issue: GitHub.