langchain-ai/langchain · error · ValueError

Failed to reach {base_url} API while trying to render your g

Error message

Failed to reach {base_url} API while trying to render your graph. Status code: {response.status_code}.

{error_msg_suffix}

What it means

When rendering via the Mermaid.INK API, a non-retryable HTTP response (anything outside the retried status set) makes _render_mermaid_using_api raise ValueError with the status code and a help suffix. It means the request reached the server but the server rejected or failed it — most often invalid Mermaid syntax (4xx) or a server-side failure (5xx).

Source

Thrown at libs/core/langchain_core/runnables/graph_mermaid.py:484

                return img_bytes

            # If we get a server error (5xx), retry
            if (
                requests.codes.internal_server_error <= response.status_code
                and attempt < max_retries
            ):
                # Exponential backoff with jitter
                sleep_time = retry_delay * (2**attempt) * (0.5 + 0.5 * random.random())  # noqa: S311 not used for crypto
                time.sleep(sleep_time)
                continue

            # For other status codes, fail immediately
            msg = (
                f"Failed to reach {base_url} API while trying to render "
                f"your graph. Status code: {response.status_code}.\n\n"
            ) + error_msg_suffix
            raise ValueError(msg)

        except (requests.RequestException, requests.Timeout) as e:
            if attempt < max_retries:
                # Exponential backoff with jitter
                sleep_time = retry_delay * (2**attempt) * (0.5 + 0.5 * random.random())  # noqa: S311 not used for crypto
                time.sleep(sleep_time)
            else:
                msg = (
                    f"Failed to reach {base_url} API while trying to render "
                    f"your graph after {max_retries} retries. "
                ) + error_msg_suffix
                raise ValueError(msg) from e

    # This should not be reached, but just in case
    msg = (
        f"Failed to reach {base_url} API while trying to render "
        f"your graph after {max_retries} retries. "
    ) + error_msg_suffix

View on GitHub (pinned to e32fa9a52e)

Solutions

1. Inspect the status code: 4xx usually means bad syntax — print the Mermaid syntax (graph.draw_mermaid()) and test it at mermaid.live
2. Simplify/escape node labels (remove quotes, braces, parentheses) and retry
3. If behind a proxy, pass proxies={...} to draw_mermaid_png or set HTTPS_PROXY
4. For 5xx from the public API, self-host mermaid.ink and pass base_url, or raise max_retries

Example fix

# before
img = graph.draw_mermaid_png()
# after (diagnose syntax first)
print(graph.draw_mermaid())  # paste into https://mermaid.live to validate
img = graph.draw_mermaid_png(max_retries=3)

syntax = graph.draw_mermaid()
# cheap sanity check before spending an API call
assert "graph" in syntax or "flowchart" in syntax or syntax.startswith(("sequenceDiagram", "stateDiagram"))

try:
    img = draw_mermaid_png(syntax)
except ValueError as e:
    if "Status code: 4" in str(e):
        print(graph.draw_mermaid())  # inspect/fix syntax
    else:
        raise

When it happens

Trigger: draw_mermaid_png() with malformed Mermaid syntax produced from an exotic graph, a background_color the API rejects, or a self-hosted base_url that errors; the response status falls in the fail-immediately branch.

Common situations: Graphs with special characters in node labels generating invalid Mermaid; corporate proxies returning 403/407; mermaid.ink outages returning 5xx; custom base_url misconfiguration.

Related errors

• Failed to reach {base_url} API while trying to render your g
• Found duplicate subgraph '{subgraph}' -- this likely means t
• Invalid draw method: {draw_method}. Supported draw methods a
• {exc}
• y should be >= 0 and < number of lines

AI-assisted analysis of langchain-ai/langchain@e32fa9a52e (2026-08-14). Data as JSON: /api/errors/37510528339e7f30. Report an issue: GitHub.