TimeoutError from mermaid.ink when rendering a LangGraph diagram

TimeoutError from mermaid.ink when rendering a LangGraph diagram

TL;DR: the timeout is mermaid.ink (the remote rendering service) being slow or down, not your graph. For a quick look use graph.get_graph().print_ascii() which renders locally with zero network. For PNGs, bump retries or switch to local Pyppeteer rendering.

requests.exceptions.ReadTimeout: HTTPSConnectionPool(host='mermaid.ink', port=443): Read timed out.
# or:
ValueError: Failed to reach https://mermaid.ink/ API while trying to render your graph after 1 retries.

When this applies

• graph.get_graph().draw_mermaid_png() raises ReadTimeout / Failed to reach mermaid.ink.
• The graph itself compiles and runs fine.
• Short node names do not cause it; the service was just flaky (multiple users confirmed).

When it does not

• If get_graph() itself errors, your graph has a structural problem. Fix that first.
• If the PNG renders but looks wrong, that is a Mermaid syntax issue, not a timeout.

Fix it

1. Use the ASCII fallback (fastest)

graph.get_graph().print_ascii()

Expected: the graph diagram prints right in your notebook/terminal. No network, no timeout, always works.

2. Retry harder

png = graph.get_graph().draw_mermaid_png(max_retries=5, retry_delay=2.0)

Expected: transient mermaid.ink slowness is absorbed by the retries.

3. Render locally with Pyppeteer

# renders in a local headless browser instead of calling mermaid.ink
png = graph.get_graph().draw_png()  # local method where available

Expected: no external service involved, so no timeout possible. Needs a browser binary on first use.

Why it happens

draw_mermaid_png() sends your graph's Mermaid definition to the public mermaid.ink API and waits for a PNG back. When that free service is slow or down, the HTTP read times out and you get this error. Your graph is irrelevant to the failure; any payload would time out the same way.

Edge cases

• Corporate proxies/VPNs sometimes block mermaid.ink outright. The ASCII fallback is the path of least resistance there.
• In CI pipelines, prefer print_ascii() or a saved PNG artifact: do not depend on a third-party free API at build time.
• The error message suggests checking your internet connection first. If other sites load fine, it is mermaid.ink, not you.

Compatibility

langgraph 0.x/1.x (Python). print_ascii() exists on all recent versions.