LangGraph can compile and succeed while skipping a required node
LangGraph compile() checks wiring, not business completeness. A purchase-to-invoice graph can succeed while skipping a node, so assert required steps ran.
This article is published in English.
Sources: The Node That Never Ran: What LangGraph Does Not Check at Compile Time
A purchase-to-invoice LangGraph workflow can compile and return success while skipping a node. That failure mode is worse than a crash: finance thinks an invoice exists when the graph never ran the step. The cause is a gap in what compile() validates—and two controls that catch it.
The reproduction
Each node prints its name. A healthy run prints every station and ends completed. Remove one edge:
graph.add_edge("create_purchase_order_from_request", "create_an_invoice")
Re-run:
Executing: load_purchase_request
Executing: validate_purchase_request_is_approved
Executing: create_purchase_order_from_request
Execution stops after purchase-order creation. The invoice line never appears. Final status stays at an intermediate value. No exception. Callers see a normal return that does not disclose the missing financial record.
What compile() actually checks
StateGraph.compile() confirms edges reference real nodes, START has an entry, and edge targets are nodes or END. It does not prove every node is reachable, that every node can reach END, or that every node executes. Tutorials that claim reachability checks oversell the API.
One gap, two failure modes
- Orphaned node — registered but no inbound edge; never runs; compile still succeeds.
- Broken path to END — a mid-graph edge deletion yields a silent partial success with a non-terminal business status.
Both look like “green” compiles.
Why the engine reports success
LangGraph treats a run that reaches a node without outgoing edges—or returns without raising—as finished. Success means “the runtime did not crash,” not “every business milestone completed.” Status fields are application conventions unless enforced.
Why END is not special enough
END is a terminal marker for edges that opt in. Nodes that simply stop do not automatically fail the invoke. Without assertions on required milestones, partial graphs look healthy.
Why the framework makes this choice
Reachability and mandatory-node analysis are program-logic problems. The library validates structural wiring, then lets product code define which nodes are required. That keeps compile fast and avoids opinionated business rules—but shifts responsibility to tests.
How to catch it
Add an explicit post-run (or graph-level) check that required nodes executed—via counters in state, callback hooks, or a completion predicate:
def find_detached_nodes(compiled):
g = compiled.get_graph()
sources = {e.source for e in g.edges}
targets = {e.target for e in g.edges}
dead_ends = [n for n in g.nodes if n not in sources and n != "__end__"]
orphans = [n for n in g.nodes if n not in targets and n != "__start__"]
return dead_ends, orphans
Also add unit tests that delete edges deliberately and expect the guard to fail. Optional static checks can walk the adjacency list for reachability from START to each required node and onward to END.
Takeaways
compile()≠ business completeness.- Prefer crashes or hard failed status over silent skips for financial workflows.
- Encode required milestones in state and assert them before acknowledging success to upstream systems.
- Document the gap for every engineer who copies a linear tutorial into production money movement.
Mapping the bug to money movement
Purchase-to-invoice is unforgiving. If create_invoice never runs, accounts payable systems, tax exports, and vendor portals diverge. Returning success with status=purchase_order_created is an application smell: upstream services interpret non-exception returns as completion. Align HTTP/job status with a checklist of required node fingerprints stored in state.
A minimal required-node contract
Maintain state["executed"] as a set reducer. Each node adds its name. Before END (or in the caller after invoke), assert {"load","validate","create_po","create_invoice"} <= executed. Missing names raise a dedicated IncompleteGraphError that monitoring can page on. This turns the framework’s permissive success into a domain-hard failure.
Static adjacency checks in CI
Serialize the graph’s edge list in tests. Compute reachability from START. Fail CI if a required node is unreachable or cannot reach END. These tests catch commented-out edges the same afternoon they are introduced—without waiting for a silent production skip.
What compile should mean in runbooks
Document for the team: “compiled” means wiring is syntactically valid. “Complete” means required business nodes executed. Onboarding that conflates the two recreates the skipped-invoice incident. Pair the doc with the reproduction snippet so new contributors can break a toy graph on purpose and watch the guard fire.
Related pitfalls
- Conditional edges that can route to nowhere if a state flag is unset.
- Retrying invoke without clearing partial side effects, creating duplicate POs while still skipping invoices.
- Relying solely on LangSmith screenshots instead of machine-checkable assertions in CI.
Treat graph topology as production data. Validate it like schemas—not like optional comments.
Walking through a healthy versus broken invoke
On a healthy graph, callbacks or print statements show load → validate → create_po → create_invoice → completion marker. Operators comparing logs to a runbook can tick each station. After an edge deletion, the invoice marker never appears, yet the Python caller still receives a dict. Downstream systems that only check transport success will post “done” into a case tool. That is how silent skips become financial incidents.
Designing status enums that cannot lie
Prefer terminal statuses that are only set by a dedicated finalization node after the required-set assertion passes: completed, failed_incomplete, failed_exception. Intermediate statuses may exist for streaming UI, but APIs that acknowledge work to other services should only emit completed after the guard. Map failed_incomplete to a compensating ticket that lists missing node names.
Interaction with checkpointers
If checkpointers resume a run after a crash, a missing edge still yields the same skip. Persistence does not create edges. Resume tests should include topology mutation fixtures. Similarly, version the graph definition beside checkpoint data so an old checkpoint is not replayed on an incompatible topology without migration logic.
Teaching the gap without fear
Engineers coming from “compile means correct” languages need a deliberate demo: break an edge in a sandbox, watch success, then enable the guard and watch failure. One live demo prevents months of assumed safety. Attach that demo script next to the purchase-to-invoice repo README.
Checklist before calling a graph “done”
- Every required business node appears in
executed. - Conditional routers have exhaustive branches including an explicit failure path.
- No node performs irreversible I/O without an idempotency key stored in state.
- Compile succeeds and reachability tests succeed in CI.
- Invoke results include a machine-readable completion flag separate from HTTP 200.
When those five hold, skipped invoices become detectable defects instead of silent successes. That is the operational bar LangGraph applications need when money or compliance is on the line—not merely a green compile log.