Conditional edge returning unknown node name
Why this matters
Conditional edges are how you route execution dynamically, but typos or logic errors in the return value will crash your graph silently at the wrong moment: often in production when a specific data path is hit.
Explanation
A add_conditional_edges() call expects the condition function to return the name of a node that actually exists in your graph. If it returns 'process_order' but you only defined nodes named 'validate' and 'send_email', langgraph will fail at runtime.
Mechanically, when graph.invoke() executes, it calls your condition function, gets back a node name string, then looks that name up in the compiled graph's node registry. If the name isn't found, a ValueError is raised immediately. This happens during execution, not during graph definition: so your code compiles fine but breaks when that branch is taken.
This is why typos in node names are particularly dangerous: your graph definition looks correct, tests pass on the happy path, then a specific input triggers the unknown node and crashes production.
Analogy
It's like telling a delivery driver to go to '123 Main Street' in your routing logic, but when the driver actually arrives at the intersection, the street doesn't exist. The dispatch center (graph definition) accepted the instruction, but reality (execution) rejects it.
Code
from langgraph.graph import StateGraph, START, END
from typing import TypedDict
class State(TypedDict):
value: int
def condition_check(state: State) -> str:
if state["value"] > 10:
return "high_path"
else:
return "low_path"
def node_high(state: State) -> State:
return {"value": state["value"] * 2}
def node_low(state: State) -> State:
return {"value": state["value"] + 1}
graph = StateGraph(State)
graph.add_node("high_path", node_high)
graph.add_node("low_path", node_low)
graph.add_edge(START, "validate")
graph.add_conditional_edges("validate", condition_check)
graph.add_edge("high_path", END)
graph.add_edge("low_path", END)
compiled = graph.compile()
try:
result = compiled.invoke({"value": 15})
print(result)
except ValueError as e:
print(f"Error caught: {e}")Error caught: Node 'validate' not found. Available nodes: ['high_path', 'low_path']
What just happened?
The graph compiled successfully because the syntax was valid. But when invoke() ran, it tried to route from START to a node called 'validate' that was never defined: only 'high_path' and 'low_path' exist. The error revealed the mismatch between what the edge definition expected and what the graph actually contains.
Common gotcha
The error happens at invoke time, not compile time. You can define a graph with a reference to a nonexistent node, and it will compile without warning. The crash only occurs when execution reaches that edge. This means your tests might pass if they don't exercise that code path.
Error recovery
ValueError: Node 'X' not foundGraph compiles but crashes mid-executionExperienced dev note
In larger graphs with many conditional branches, this becomes insidious because tests only cover the happy path. Use a validation helper: after defining all nodes, iterate your conditional edges and assert every returned node name exists in the graph's registry. Better yet, return a Literal type hint on your condition function so type checkers catch the error before runtime.
Check your understanding
If your condition function returns 'payment_retry' but you only defined nodes 'payment_success' and 'payment_fail', at what moment will the error appear: during graph definition, during compilation, or during invoke?
Show answer hint
The correct answer identifies that the error appears during invoke(), not earlier. Graph definition and compilation succeed because they only validate syntax, not the semantic existence of referenced nodes. The lookup happens at execution time.