deepset-ai/haystack · error · ValueError

Invalid theme: {params['theme']}. Valid options are: {valid_

Error message

Invalid theme: {params['theme']}. Valid options are: {valid_themes}.

What it means

mermaid.ink supports a fixed set of themes. Haystack validates params['theme'] against that list and raises this ValueError for unknown themes.

Source

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

    :raises ValueError:
        If any parameter is invalid or does not match the expected format.
    """
    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.")

View on GitHub (pinned to e318778c9b)

Solutions

1. Use one of the themes listed in the error message (e.g. 'default', 'neutral', 'dark', 'forest')
2. Remove 'theme' to keep the 'neutral' default

Example fix

// before
pipeline.draw(path="g.png", params={"theme": "light"})  # ValueError
// after
pipeline.draw(path="g.png", params={"theme": "dark"})

if params.get("theme", "neutral") not in {"default", "neutral", "dark", "forest"}:
    raise ValueError("unsupported theme")

def valid_theme(params: dict) -> bool:
    return params.get("theme", "neutral") in {"default", "neutral", "dark", "forest"}

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

When it happens

Trigger: Passing params={'theme': 'light'} or a custom theme string instead of a supported one such as 'default', 'neutral', 'dark', 'forest'.

Common situations: Assuming CSS-like theme names; porting settings from other mermaid tooling.

Related errors

• Invalid image format: {params['format']}. Valid options are:
• Invalid image type: {params['type']}. Valid options are: {va
• Width must be an integer.
• Height must be an integer.
• Scale must be a number between 1 and 3.

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