deepset-ai/haystack · error · ValueError

Invalid format: {endpoint_format}. Valid options are 'img',

Error message

Invalid format: {endpoint_format}. Valid options are 'img', 'svg', or 'pdf'.

What it means

The Mermaid endpoint is chosen from the 'format' parameter ('img', 'svg', or 'pdf' map to mermaid.ink endpoints). _to_mermaid_image raises this ValueError when format is anything else, before any network request is made.

Source

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

    _validate_mermaid_params(params)

    theme = params.get("theme")
    init_params = json.dumps({"theme": theme})

    # Copy the graph to avoid modifying the original
    graph_styled = _to_mermaid_text(graph.copy(), init_params, super_component_mapping)
    json_string = json.dumps({"code": graph_styled})

    # Compress the JSON string with zlib (RFC 1950)
    compressor = zlib.compressobj(level=9, wbits=15)
    compressed_data = compressor.compress(json_string.encode("utf-8")) + compressor.flush()
    compressed_url_safe_base64 = base64.urlsafe_b64encode(compressed_data).decode("utf-8").strip()

    # Determine the correct endpoint
    endpoint_format = params.get("format", "img")  # Default to /img endpoint
    if endpoint_format not in {"img", "svg", "pdf"}:
        raise ValueError(f"Invalid format: {endpoint_format}. Valid options are 'img', 'svg', or 'pdf'.")

    # Construct the URL without query parameters
    url = f"{server_url}/{endpoint_format}/pako:{compressed_url_safe_base64}"

    # Add query parameters adhering to mermaid.ink documentation
    query_params = []
    for key, value in params.items():
        if key not in {"theme", "format"}:  # Exclude theme (handled in init_params) and format (endpoint-specific)
            if value is True:
                query_params.append(f"{key}")
            else:
                query_params.append(f"{key}={value}")

    if query_params:
        url += "?" + "&".join(query_params)

    logger.debug("Rendering graph at {url}", url=url)
    try:

View on GitHub (pinned to e318778c9b)

Solutions

1. Use format in {'img', 'svg', 'pdf'}; for JPEG set {'format': 'img', 'type': 'jpeg'}
2. Omit 'format' entirely for the default PNG image
3. Check the current draw() docstring for valid values

Example fix

// before
params = {"format": "png"}
// after
params = {"format": "img", "type": "png"}

VALID = {"img", "svg", "pdf"}
fmt = params.get("format", "img")
if fmt not in VALID:
    raise ValueError(f"format must be one of {VALID}, got {fmt!r}")

def is_valid_format(fmt) -> bool:
    return fmt in {"img", "svg", "pdf"}

try:
    pipeline.draw(path="graph.png", params=params)
except ValueError as e:
    logger.error("Bad format param: %s", e)

When it happens

Trigger: Calling Pipeline.draw() or show() with a Mermaid params dict like {'format': 'png'}, {'format': 'jpeg'}, or {'format': 'jpg'} — formats that are valid image types but not valid endpoint formats.

Common situations: Users confuse the 'type' parameter (png/jpeg for img endpoint) with 'format'; older Haystack versions had different format options; building params from docs for a different tool.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Paper size must be a string (e.g., 'a4', 'a3').
• Landscape must be a boolean.
• Tool execution requires at least one tool.
• 'dimension' must be a positive integer.
• 'dimension' must be a positive integer.

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