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 after {max_retries} retries. {error_msg_suffix}

What it means

After exhausting max_retries on retryable failures, a requests.RequestException or Timeout escapes the retry loop and is re-raised as this ValueError (with `from e` preserving the cause). It means the Mermaid.INK endpoint (default https://mermaid.ink or your base_url) could not be reached at all or timed out on every attempt.

Source

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

            # 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
    raise ValueError(msg)

View on GitHub (pinned to e32fa9a52e)

Solutions

1. Verify network access to the endpoint: curl -I https://mermaid.ink
2. Configure the proxy via the proxies argument or HTTPS_PROXY env var
3. Increase max_retries and retry_delay for flaky links
4. For offline use, self-host the mermaid.ink service and pass base_url, or switch to draw_method=MermaidDrawMethod.PYPPETEER with local Chromium

Example fix

# before
img = graph.draw_mermaid_png()  # network unreachable
# after
img = graph.draw_mermaid_png(
    max_retries=3,
    retry_delay=2.0,
    base_url="https://your-internal-mermaid",
)

import socket
socket.getaddrinfo("mermaid.ink", 443)  # fail fast if DNS/egress blocked

try:
    img = draw_mermaid_png(syntax, max_retries=3, retry_delay=2.0)
except ValueError as e:
    if "after" in str(e) and "retries" in str(e):
        img = render_locally_with_pyppeteer(syntax)  # offline fallback

When it happens

Trigger: draw_mermaid_png() with no internet, DNS failure, firewall blocking mermaid.ink, an unreachable self-hosted base_url, or timeouts with max_retries exhausted.

Common situations: Offline/air-gapped environments, containers with restricted egress, corporate proxies not configured, mermaid.ink temporarily down.

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/39c42bfad9617436. Report an issue: GitHub.