langchain-ai/langchain · error · ValueError

Found duplicate subgraph '{subgraph}' -- this likely means t

Error message

Found duplicate subgraph '{subgraph}' -- this likely means that you're reusing a subgraph node with the same name. Please adjust your graph to have subgraph nodes with unique names.

What it means

While generating Mermaid output, draw_mermaid tracks subgraph names it has already emitted. When two subgraph nodes share the same final name (prefix segment after the last ':'), Mermaid syntax would be ambiguous, so it raises this ValueError. It almost always means the same compiled subgraph was added as two nodes with the same name.

Source

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

        common_prefix = ":".join(
            src for src, tgt in zip(src_parts, tgt_parts, strict=False) if src == tgt
        )
        edge_groups.setdefault(common_prefix, []).append(edge)

    seen_subgraphs = set()

    def add_subgraph(edges: list[Edge], prefix: str) -> None:
        nonlocal mermaid_graph
        self_loop = len(edges) == 1 and edges[0].source == edges[0].target
        if prefix and not self_loop:
            subgraph = prefix.rsplit(":", maxsplit=1)[-1]
            if subgraph in seen_subgraphs:
                msg = (
                    f"Found duplicate subgraph '{subgraph}' -- this likely means that "
                    "you're reusing a subgraph node with the same name. "
                    "Please adjust your graph to have subgraph nodes with unique names."
                )
                raise ValueError(msg)

            seen_subgraphs.add(subgraph)
            mermaid_graph += f"\tsubgraph {subgraph}\n"

            # Add nodes that belong to this subgraph
            if with_styles and prefix in subgraph_nodes:
                for key, node in subgraph_nodes[prefix].items():
                    mermaid_graph += render_node(key, node)

        for edge in edges:
            source, target = edge.source, edge.target

            # Add BR every wrap_label_n_words words
            if edge.data is not None:
                edge_data = edge.data
                words = str(edge_data).split()  # Split the string into words
                # Group words into chunks of wrap_label_n_words size
                if len(words) > wrap_label_n_words:

View on GitHub (pinned to e32fa9a52e)

Solutions

Give each subgraph node a unique name when adding it to the parent graph
If the same subgraph must appear twice, create two separately-named instances/wrappers
Check graph.nodes for ids sharing the same suffix after ':' before drawing

Example fix

# before
parent.add_node("agent", agent_subgraph)
parent.add_node("agent", agent_subgraph)  # duplicate
# after
parent.add_node("agent_1", agent_subgraph)
parent.add_node("agent_2", agent_subgraph)

Defensive patterns

Strategy: validation

Validate before calling

names = [nid.split(":")[-1] for nid in graph.nodes]
dupes = {n for n in names if names.count(n) > 1}
assert not dupes, f"duplicate subgraph names: {dupes}"

Type guard

def has_unique_subgraph_names(graph) -> bool:
    names = [n.split(":")[-1] for n in graph.nodes]
    return len(names) == len(set(names))

Try / catch

try:
    graph.draw_mermaid()
except ValueError as e:
    if "duplicate subgraph" in str(e):
        rename_offending_nodes(graph)

Prevention

Name every subgraph node uniquely at construction time
Never add the same compiled subgraph under one name twice; wrap with distinct names

When it happens

Trigger: A graph that reuses the same subgraph instance (or same-named subgraph nodes) in two places, then calling graph.draw_mermaid() on it. The subgraph name is the node id after the last ':' in the prefixed id.

Common situations: Building a state graph where the same compiled subgraph is wired into two nodes without renaming; copy-pasting node definitions; LangGraph-style multi-agent graphs reusing a tool subgraph.

Related errors

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