langgraph subgraph "Node 'x' already exists" duplicate node error

TL;DR

"Node 'x' already exists" means two add_node calls used the same name in one graph. Find the duplicate registration and rename one side, or compose subgraphs as single compiled nodes so inner names stay namespaced.

Error

ValueError: Node 'x' already exists.

Steps

1. Find the duplicate. Search your graph-building code for every add_node using that name:

# look for two calls like this in the same builder
builder.add_node("x", some_function)

Expected output: you find two registrations of the same name, often one in a helper that runs twice or a copy-pasted block.

2. Rename one side so every name in the graph is unique:

builder.add_node("x_validate", validate_fn)
builder.add_node("x_enrich", enrich_fn)

Expected output: the builder accepts both nodes. Update any edges that referenced the old shared name.

3. If the collision comes from composing subgraphs, add each subgraph as one compiled node instead of merging builders:

builder.add_node("subflow", subgraph_builder.compile())

Expected output: the subgraph's internal node names stay namespaced inside it and can no longer collide with the parent graph.

4. Rebuild and verify the full node list:

graph = builder.compile()
print(list(graph.get_graph().nodes))

Expected output: every name appears exactly once and the graph compiles cleanly.

When to use

• The same node name is registered twice in one builder
• Two subgraphs merged into one builder share node names
• Nodes are added in a loop and the name does not vary per iteration

When not to use

• The error is "Node 'x' not found" (thats a typo in an edge, the opposite problem)
• Edges route to the wrong node (thats routing logic, not naming)
• Two graphs each use the name independently and never merge (no conflict)

Variant phrasings

duplicate node when adding nodes in a loop

The loop variable is not part of the node name. Include it: add_node(f"fetch_{source}", ...).

collision after merging two graph builders

Merging builders concatenates their namespaces. Compile each subgraph separately and add them as single nodes instead.

Why it happens

Node names are the graph's address space: edges, state updates, and debugging all reference nodes by name. LangGraph enforces uniqueness at build time because a duplicate name would make edges ambiguous.

Edge cases

• Names are case-sensitive: "Fetch" and "fetch" are different nodes, which can confuse and also collide visually.
• A parent graph and a compiled subgraph added as a single node may reuse inner names freely; the collision only happens when builders are merged.
• Dynamically generated graphs should assert name uniqueness before compiling, or the error surfaces late.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstYvvr7dIo2aXJM5eM4XKdw