fix(langgraph): add compile-time detection of detached nodes

[Saakshi Gupta (saakshigupta2002)]

Pull Request: Compile-time Detection of Detached Nodes

Summary

This PR introduces optional validation to detect and handle detached nodes during graph compilation. Detached nodes are either:

• Unreachable nodes: Nodes that are not reachable from START
• Dead-end nodes: Nodes that have no path to END

These scenarios often indicate bugs in graph construction that are currently silently ignored, leading to hard-to-debug issues in production.

Changes

New Parameter: on_detached_nodes

Added a new on_detached_nodes parameter to StateGraph.compile() with three modes:

Mode	Behavior
"warn" (default)	Log a warning but compile successfully
"raise"	Raise a ValueError and fail compilation
"ignore"	Disable detection (useful for dynamic routing)

Implementation Details

Detection is implemented in CompiledStateGraph._check_detached_nodes(), which leverages the existing compiled channel/writer infrastructure rather than building a separate graph representation.

After attach_node, attach_edge, and attach_branch populate the channel system, the method:

1. Scans all nodes' writers to collect every channel that is written to via ChannelWriteEntry and ChannelWriteTupleEntry.static declarations
2. Detects unreachable nodes by checking if any writer targets the node's branch:to:{name} trigger channel — if not, nothing routes to this node
3. Detects dead-end nodes by checking if a node has any outgoing connection: writers to branch:to:* channels, explicit edges to END in the builder, conditional branches, or Command destinations declared in static

This approach is idiomatic to LangGraph's internal architecture and avoids duplicating connectivity information that the channel system already captures.

Example Usage

from langgraph.graph import StateGraph, START, END

class State(TypedDict):
    messages: list[str]

graph = StateGraph(State)
graph.add_node("process", process_fn)
graph.add_node("orphan", orphan_fn)  # Forgot to connect this!
graph.add_edge(START, "process")
graph.add_edge("process", END)

# Default behavior: warns about detached nodes but compiles
compiled = graph.compile()  # Logs: "Found unreachable node(s): ['orphan']"

# Strict mode: fails compilation
compiled = graph.compile(on_detached_nodes="raise")  # Raises ValueError

# For dynamic routing: disable detection
compiled = graph.compile(on_detached_nodes="ignore")  # No warnings

Important Notes for Dynamic Routing

For nodes that use Command objects or conditional edges without explicit mappings, the destinations cannot be detected at compile time. In such cases:

1. Use the destinations parameter when adding nodes:

   graph.add_node(
       "router",
       router_fn,
       destinations={"target_a": "Label A", "target_b": "Label B"}
   )

2. Or set on_detached_nodes="ignore" to disable validation.

Test Plan

Added comprehensive test coverage for:

• Single unreachable node detection
• Multiple unreachable nodes detection
• Sink node without path to END detection
• Warning mode logs warning but compiles
• Ignore mode suppresses warnings
• Conditional edges with explicit mapping
• Conditional edges without mapping (dynamic routing)
• Command destinations (dict format)
• Command destinations (tuple format)
• Multi-source waiting edges
• Diamond pattern with conditional routing
• Cyclic graphs with conditional exit
• Minimal single node graph
• Command with goto=END
• Parallel branches all reaching END
• Mixed unreachable and sink nodes

Backwards Compatibility

This change is fully backwards compatible:

• Default behavior is "warn", which only logs warnings
• Existing code continues to work without modification
• No breaking changes to the API

Related Issue

Fixes: #6735

---

Files Changed

File	Changes
libs/langgraph/langgraph/graph/state.py	Added _check_detached_nodes() to CompiledStateGraph, added on_detached_nodes parameter to compile()
libs/langgraph/tests/test_pregel.py	Added 16 test cases

[William FH (hinthornw)]

It should be enough to check the channels if you wanted

[Saakshi Gupta (saakshigupta2002)]

It should be enough to check the channels if you wanted

Hey, thanks for taking a look! :) That's a great point! I hadn't considered using the channels directly for this. Since the branch:to:{node} channels already capture the connectivity after edges and branches are attached, checking which channels have no writers (unreachable) and which nodes don't write to any outgoing channel (dead ends) would be way cleaner than building a separate adjacency list and doing BFS on top of it.

I'll rework the implementation to move the detection into the compiled graph stage where the channel info is available. Should keep things a lot simpler and more in line with how the rest of the codebase works. Will push an update soon!