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

Not specified by the original author.

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

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

Thread query: 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.

Not specified by the original author.

Subgraph forgets its state when the parent graph invokes it a second time

TL;DR: do not wire a compiled subgraph directly as a node when the parent calls it repeatedly. Wrap it in a node function that invokes the subgraph, and its state persists across calls. Direct wiring can cause the subgraph to run once and then silently reuse stale or empty state.

# no exception. the symptom: print() inside the subgraph node fires once,
# but the parent routes to the subgraph three times. the second and third
# visits see empty state instead of the accumulated state from run one.

When this applies

• A parent graph calls the same subgraph node more than once (loop, follow-up questions, retries).
• First visit works; later visits act like a fresh subgraph.
• A debug print inside the subgraph confirms it only executed once.

When it does not

• If the PARENT loses state between separate invoke() calls, that is a checkpointer/thread_id issue, not this.
• If the subgraph errors, look at the actual exception instead.

Fix it

1. Wrap the subgraph in a node function

# instead of: parent.add_node("agent", subgraph)
# do this:

def agent_node(state: ParentState):
    # invoke the compiled subgraph fresh each time the parent visits this node
    return subgraph.invoke({"messages": state["messages"]})

parent.add_node("agent", agent_node)

Expected: your debug print inside the subgraph now fires on every visit, and state accumulates across visits.

2. Pass state in explicitly, read it back explicitly

def agent_node(state: ParentState):
    result = subgraph.invoke({
        "messages": state["messages"],
        "subgraph_state": state.get("subgraph_state"),
    })
    return {"messages": result["messages"]}

Expected: the parent only keeps the keys it declares; the subgraph keeps its own. Nothing leaks or gets silently dropped.

3. Give the subgraph its own thread namespace if it has a checkpointer

If both parent and subgraph use checkpointers, the subgraph's checkpoints live under a namespace. When invoking manually, keep the namespace stable so the subgraph resumes instead of restarting:

def agent_node(state: ParentState, config):
    sub_config = {"configurable": {"thread_id": config["configurable"]["thread_id"]}}
    return subgraph.invoke({"messages": state["messages"]}, sub_config)

Expected: subgraph.get_state(sub_config) shows history across parent visits.

Why it happens

A compiled subgraph used directly as a node is treated as a single node by the parent's Pregel loop. Its internal super-steps are managed by the parent, and on repeat visits the parent may not re-enter the subgraph's own loop the way a fresh invoke() would. A wrapper node function makes each visit a genuine fresh invocation with its own state lifecycle.

Edge cases

• Streaming: with the wrapper, use subgraph.stream() inside the node and forward events if the parent needs them.
• Interrupts inside the subgraph still work, but the interrupt surfaces at the wrapper node. Resume with the parent's config as usual.
• Performance: each visit re-enters the subgraph from its entry point. If you need the subgraph to continue mid-loop across visits, keep its checkpointer and pass the same thread config.

Compatibility

langgraph 0.2.x and 1.x (Python). The pattern (node function wrapping subgraph.invoke) works in all versions.

GitHub issue langchain-ai/langgraph#3020 ("Subgraph forgets its state of the first run when it is invoked the second time in a parent graph", 11 comments, with a TL;DR summary comment from the reporter): a nested multi-agent graph ran the same subgraph on follow-up questions and the subgraph's state from the first run was gone. A commenter verified the subgraph node function only executed once instead of the expected three times, and the suggested fix is to add a node function that invokes the subgraph rather than wiring the compiled subgraph directly as a node. Source: https://github.com/langchain-ai/langgraph/issues/3020.

Not specified by the original author.

TL;DR

Trace one run step by step (or log node entries). Two distinct causes, different fixes: 1.

Steps

1. Trace one run step by step (or log node entries). Ask: does this graph have a path to END in the number of steps you expect? Watch for a pair of nodes bouncing back and forth.
2. Two distinct causes, different fixes:
3. Infinite loop: a conditional edge whose condition never selects the exit, or literal add_edge("a", "b") + add_edge("b", "a") with no conditional exit.
4. Legitimately deep graph: many sequential steps, large fan-outs, long agent loops that really do need hundreds of steps.
5. - Loop: fix the condition so some path reaches END. This is the fix in most cases.

• Deep: raise it for that invocation:

graph.invoke({...}, {"recursion_limit": 1000})

5. Re-run and confirm it terminates. If you raised the limit, also confirm the step count is sane; a graph that needs 900 steps to do a 10-step job has a logic problem, not a limit problem.

When to use

You are seeing this: GRAPHRECURSIONLIMIT: the StateGraph reached the maximum number of steps before hitting a stop condition. Use this skill when you run into "Diagnose: GraphRecursionError / GRAPHRECURSIONLIMIT in a LangGraph run".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

Two distinct causes, different fixes: 1.

Diagnostic procedure grounded in the official GRAPHRECURSIONLIMIT error page, verified 2026-09-26. Error page: docsgchain.com/oss/python/langgraph/errors/GRAPHRECURSIONLIMIT