Skip to content

Commit 79befe6

Browse files
fix: nested subgraph inherits parent checkpoint_ns (regression in 1.2.3) (#8053)
Closes #8038 ## Description The `ensure_config` merge introduced in #7926 caused a child graph invoked inside a parent node to inherit the parent task's `checkpoint_ns` from the ambient run context (`var_child_runnable_config`), so the child's checkpoints were written under an unreadable namespace and re-ran from scratch each turn (#8038). The first explicitly passed `configurable` that carries a checkpoint coordinate (a `thread_id`, or any `checkpoint_ns`/`checkpoint_id`/`checkpoint_map`) now replaces the ambient one, while subsequent explicit configs still shallow-merge — preserving #7926's `with_config(...)` semantics. ## Contract `ensure_config` merges an explicit `configurable` over the ambient run context (`var_child_runnable_config`) with one rule: **an explicit `configurable` that supplies its own checkpoint coordinate addresses its own checkpoint lineage, so the ambient `configurable` is dropped rather than merged over.** Coordinate keys are `thread_id`, `checkpoint_ns`, `checkpoint_id`, and `checkpoint_map` (grouped as `_CHECKPOINT_COORDINATE_KEYS`). A non-coordinate `configurable` keeps the ambient and shallow-merges over it. Below, each case shows the parent/child graph wiring that triggers it and the resulting namespacing. The child is always a compiled subgraph invoked from inside a parent node. ### 1. Subgraph invoked with no new config → ambient inherited ```python child = StateGraph(ChildState).add_node("n", child_node).add_edge(START, "n").compile(checkpointer=checkpointer) def parent_node(state): child.invoke({}, config=None) # no explicit configurable return {"result": "ok"} parent = StateGraph(ParentState).add_node("p", parent_node).add_edge(START, "p").compile(checkpointer=checkpointer) parent.invoke({"result": ""}, config={"configurable": {"thread_id": "parent"}}) ``` Child inherits the parent task's `checkpoint_ns` (`p:<parent-task>`); its checkpoints are written as a discoverable child of the parent run. Pre-#7926 behavior, unchanged. ### 2. Subgraph invoked with a new thread_id → ambient dropped ```python child = StateGraph(ChildState).add_node("n", child_node).add_edge(START, "n").compile(checkpointer=checkpointer) child_config = {"configurable": {"thread_id": str(uuid4())}} def parent_node(state): child.invoke({}, config=child_config) # explicit new thread_id return {"result": "ok"} parent = StateGraph(ParentState).add_node("p", parent_node).add_edge(START, "p").compile(checkpointer=checkpointer) parent.invoke({"result": ""}, config={"configurable": {"thread_id": "parent"}}) ``` Child starts its own lineage on `child_config`'s thread; `checkpoint_ns == ""`; `child.get_state(child_config)` reads back state across repeated parent turns. Fixes #8038. ### 3. Subgraph invoked with the same thread_id as parent → ambient still dropped ```python child = StateGraph(ChildState).add_node("n", child_node).add_edge(START, "n").compile(checkpointer=checkpointer) def parent_node(state): # reuses the parent's thread_id as the child's own child.invoke({}, config={"configurable": {"thread_id": state["parent_thread"]}}) return {"result": "ok"} parent = StateGraph(ParentState).add_node("p", parent_node).add_edge(START, "p").compile(checkpointer=checkpointer) parent_thread = str(uuid4()) parent.invoke({"parent_thread": parent_thread, "result": ""}, config={"configurable": {"thread_id": parent_thread}}) ``` Child addresses its own root namespace on the shared thread; `checkpoint_ns == ""`. The parent task's `checkpoint_ns` must not leak in, or `child.get_state({"configurable": {"thread_id": parent_thread}})` returns empty state and the child re-runs from scratch each turn. ### 4. Subagent invoked with a non-coordinate key only → ambient inherited ```python child = StateGraph(ChildState).add_node("n", child_node).add_edge(START, "n").compile(checkpointer=checkpointer) def parent_node(state): # ls_agent_type is not a checkpoint coordinate, so ambient is kept child.invoke({}, config={"configurable": {"ls_agent_type": "subagent"}}) return {"result": "ok"} parent = StateGraph(ParentState).add_node("p", parent_node).add_edge(START, "p").compile(checkpointer=checkpointer) parent.invoke({"result": ""}, config={"configurable": {"thread_id": "parent"}}) ``` Child remains a discoverable child of the parent run; ambient `thread_id` and `checkpoint_ns` preserved (deepagents `task` tool pattern). ### 5. with_config(...) + invoke-time thread_id → ambient dropped, then merged ```python # child compiled with a non-coordinate configurable via with_config child = ( StateGraph(ChildState) .add_node("n", child_node) .add_edge(START, "n") .compile(checkpointer=checkpointer) .with_config({"configurable": {"ls_agent_type": "root"}}) ) def parent_node(state): # invoke-time config supplies the thread_id; with_config's ls_agent_type survives child.invoke({}, config={"configurable": {"thread_id": "child"}}) return {"result": "ok"} parent = StateGraph(ParentState).add_node("p", parent_node).add_edge(START, "p").compile(checkpointer=checkpointer) parent.invoke({"result": ""}, config={"configurable": {"thread_id": "parent"}}) ``` First coordinate-bearing config (`thread_id`) drops the ambient; subsequent explicit configs still shallow-merge, so `ls_agent_type` survives alongside `thread_id`. Preserves #7926 `with_config(...)` semantics. ### Regression note Cases 1, 4, and 5 are the pre-#7926 behavior and are preserved unchanged. Cases 2 and 3 fix the regression introduced by #7926: an explicit `thread_id` resets the ambient even when it equals the ambient thread id, because a child reusing the parent's thread id still addresses its own root namespace on that thread, not the parent task's. ## Self-Hosted Release Note Fix regression where a nested subgraph with its own `thread_id` invoked inside a parent node lost its persisted state across turns. ## Test Plan - [x] `pytest tests/test_subgraph_persistence.py -k test_child_with_own_thread_id_keeps_namespace` (case 2) - [x] `pytest tests/test_utils.py -k ensure_config_explicit_configurable_replaces_ambient` (case 2) - [x] `pytest tests/test_utils.py -k ensure_config_ambient_inherited_when_no_explicit_configurable` (case 1) - [x] `pytest tests/test_utils.py -k ensure_config_non_coordinate_config_keeps_ambient_checkpoint_ns` (case 4) - [x] `pytest tests/test_utils.py -k ensure_config_explicit_configurables_still_merge_over_ambient` (case 5) - [x] `pytest tests/test_utils.py -k ensure_config_same_thread_id_still_clears_ambient` (case 3) Made by [Open SWE](https://openswe.vercel.app) --------- Co-authored-by: Nick Hollon <[email protected]> Co-authored-by: open-swe[bot] <[email protected]>
1 parent 9af2521 commit 79befe6

5 files changed

Lines changed: 214 additions & 0 deletions

File tree

‎libs/langgraph/langgraph/_internal/_config.py‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
from langgraph.checkpoint.base import CheckpointMetadata
2121

2222
from langgraph._internal._constants import (
23+
_CHECKPOINT_COORDINATE_KEYS,
2324
CONF,
2425
CONFIG_KEY_CHECKPOINT_ID,
2526
CONFIG_KEY_CHECKPOINT_MAP,
@@ -342,6 +343,28 @@ def ensure_config(*configs: RunnableConfig | None) -> RunnableConfig:
342343
if _is_not_empty(v)
343344
},
344345
)
346+
# An explicit config that supplies its own checkpoint coordinate (a
347+
# thread_id, or any checkpoint_ns/checkpoint_id/checkpoint_map) is addressing
348+
# its own checkpoint lineage, so drop the inherited ambient configurable
349+
# rather than merging over it: a child graph invoked inside a parent node
350+
# would otherwise write its checkpoints under the parent's namespace and
351+
# never find them again. An explicit thread_id resets even when it equals the
352+
# ambient one, since a child reusing the parent's thread id still addresses
353+
# its own root namespace, not the parent task's. Configs that only refine
354+
# other keys keep the ambient and shallow-merge over it below.
355+
if empty.get(CONF):
356+
for config in configs:
357+
if config is None:
358+
continue
359+
explicit_configurable = config.get(CONF)
360+
if not explicit_configurable:
361+
continue
362+
if any(
363+
_is_not_empty(explicit_configurable.get(k))
364+
for k in _CHECKPOINT_COORDINATE_KEYS
365+
):
366+
empty[CONF] = {}
367+
break
345368
for config in configs:
346369
if config is None:
347370
continue

‎libs/langgraph/langgraph/_internal/_constants.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,15 @@
9595
OVERWRITE = sys.intern("__overwrite__")
9696
# dict key for the overwrite value, used as `{'__overwrite__': value}`
9797

98+
# Checkpoint coordinate keys: when any of these appear in an explicit
99+
# configurable, the caller is addressing its own checkpoint lineage.
100+
_CHECKPOINT_COORDINATE_KEYS = (
101+
CONFIG_KEY_THREAD_ID,
102+
CONFIG_KEY_CHECKPOINT_NS,
103+
CONFIG_KEY_CHECKPOINT_ID,
104+
CONFIG_KEY_CHECKPOINT_MAP,
105+
)
106+
98107
# redefined to avoid circular import with langgraph.constants
99108
_TAG_HIDDEN = sys.intern("langsmith:hidden")
100109

‎libs/langgraph/tests/test_subgraph_persistence.py‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -639,3 +639,49 @@ def call_both(state: ParentState) -> dict:
639639
"broccoli round 2",
640640
"Veggie: broccoli round 2",
641641
]
642+
643+
644+
def test_child_with_own_thread_id_keeps_namespace(
645+
sync_checkpointer: BaseCheckpointSaver,
646+
) -> None:
647+
"""A child graph invoked from inside a parent node with its own thread_id
648+
must store and read its checkpoint under its own namespace, not inherit the
649+
parent task's checkpoint_ns.
650+
"""
651+
652+
class ChildState(TypedDict):
653+
count: int
654+
655+
def child_node(state: ChildState) -> dict:
656+
return {"count": (state.get("count") or 0) + 1}
657+
658+
child = (
659+
StateGraph(ChildState)
660+
.add_node("n", child_node)
661+
.add_edge(START, "n")
662+
.compile(checkpointer=sync_checkpointer)
663+
)
664+
665+
child_thread = str(uuid4())
666+
child_config = {"configurable": {"thread_id": child_thread}}
667+
668+
def parent_node(state: ParentState) -> dict:
669+
child.invoke({}, config=child_config)
670+
return {"result": "ok"}
671+
672+
parent = (
673+
StateGraph(ParentState)
674+
.add_node("p", parent_node)
675+
.add_edge(START, "p")
676+
.compile(checkpointer=sync_checkpointer)
677+
)
678+
parent_config = {"configurable": {"thread_id": str(uuid4())}}
679+
680+
parent.invoke({"result": ""}, config=parent_config)
681+
state1 = child.get_state(child_config)
682+
assert state1.values.get("count") == 1
683+
assert state1.config["configurable"]["checkpoint_ns"] == ""
684+
685+
parent.invoke({"result": ""}, config=parent_config)
686+
state2 = child.get_state(child_config)
687+
assert state2.values.get("count") == 2

‎libs/langgraph/tests/test_subgraph_persistence_async.py‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -660,3 +660,50 @@ async def call_both(state: ParentState) -> dict:
660660
"broccoli round 2",
661661
"Veggie: broccoli round 2",
662662
]
663+
664+
665+
@NEEDS_CONTEXTVARS
666+
async def test_child_with_own_thread_id_keeps_namespace_async(
667+
async_checkpointer: BaseCheckpointSaver,
668+
) -> None:
669+
"""A child graph invoked from inside a parent node with its own thread_id
670+
must store and read its checkpoint under its own namespace, not inherit the
671+
parent task's checkpoint_ns.
672+
"""
673+
674+
class ChildState(TypedDict):
675+
count: int
676+
677+
def child_node(state: ChildState) -> dict:
678+
return {"count": (state.get("count") or 0) + 1}
679+
680+
child = (
681+
StateGraph(ChildState)
682+
.add_node("n", child_node)
683+
.add_edge(START, "n")
684+
.compile(checkpointer=async_checkpointer)
685+
)
686+
687+
child_thread = str(uuid4())
688+
child_config = {"configurable": {"thread_id": child_thread}}
689+
690+
async def parent_node(state: ParentState) -> dict:
691+
await child.ainvoke({}, config=child_config)
692+
return {"result": "ok"}
693+
694+
parent = (
695+
StateGraph(ParentState)
696+
.add_node("p", parent_node)
697+
.add_edge(START, "p")
698+
.compile(checkpointer=async_checkpointer)
699+
)
700+
parent_config = {"configurable": {"thread_id": str(uuid4())}}
701+
702+
await parent.ainvoke({"result": ""}, config=parent_config)
703+
state1 = await child.aget_state(child_config)
704+
assert state1.values.get("count") == 1
705+
assert state1.config["configurable"]["checkpoint_ns"] == ""
706+
707+
await parent.ainvoke({"result": ""}, config=parent_config)
708+
state2 = await child.aget_state(child_config)
709+
assert state2.values.get("count") == 2

‎libs/langgraph/tests/test_utils.py‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -506,6 +506,95 @@ def test_ensure_config_configurable_later_wins_per_key() -> None:
506506
assert merged["configurable"]["only_b"] == "B"
507507

508508

509+
def test_ensure_config_explicit_configurable_replaces_ambient() -> None:
510+
# An explicit checkpoint coordinate (here a new thread_id) starts a fresh
511+
# lineage and drops the ambient run context (e.g. a parent task's
512+
# checkpoint_ns), so a child graph does not inherit it.
513+
from langchain_core.runnables.config import var_child_runnable_config
514+
515+
token = var_child_runnable_config.set(
516+
{"configurable": {"checkpoint_ns": "p:parent-task", "checkpoint_id": "cid"}}
517+
)
518+
try:
519+
merged = ensure_config({"configurable": {"thread_id": "child"}})
520+
finally:
521+
var_child_runnable_config.reset(token)
522+
assert merged["configurable"]["thread_id"] == "child"
523+
assert "checkpoint_ns" not in merged["configurable"]
524+
assert "checkpoint_id" not in merged["configurable"]
525+
526+
527+
def test_ensure_config_ambient_inherited_when_no_explicit_configurable() -> None:
528+
# With no explicit configurable, the ambient run context is inherited
529+
# unchanged (stateless subgraph / interrupt-resume pattern).
530+
from langchain_core.runnables.config import var_child_runnable_config
531+
532+
token = var_child_runnable_config.set(
533+
{"configurable": {"checkpoint_ns": "p:parent-task"}}
534+
)
535+
try:
536+
merged = ensure_config({"tags": ["t"]})
537+
finally:
538+
var_child_runnable_config.reset(token)
539+
assert merged["configurable"]["checkpoint_ns"] == "p:parent-task"
540+
541+
542+
def test_ensure_config_explicit_configurables_still_merge_over_ambient() -> None:
543+
# A new thread_id drops the ambient, but explicit configs still shallow-merge
544+
# among themselves, so a with_config(...) value (ls_agent_type) survives
545+
# alongside an invoke-time thread_id.
546+
from langchain_core.runnables.config import var_child_runnable_config
547+
548+
token = var_child_runnable_config.set(
549+
{"configurable": {"checkpoint_ns": "p:parent-task"}}
550+
)
551+
try:
552+
merged = ensure_config(
553+
{"configurable": {"ls_agent_type": "root"}},
554+
{"configurable": {"thread_id": "child"}},
555+
)
556+
finally:
557+
var_child_runnable_config.reset(token)
558+
assert merged["configurable"]["ls_agent_type"] == "root"
559+
assert merged["configurable"]["thread_id"] == "child"
560+
assert "checkpoint_ns" not in merged["configurable"]
561+
562+
563+
def test_ensure_config_non_coordinate_config_keeps_ambient_checkpoint_ns() -> None:
564+
# A nested subagent is invoked with a non-coordinate configurable key
565+
# (ls_agent_type) and no thread_id; it must keep the inherited checkpoint_ns
566+
# so it stays a discoverable child of the parent run (deepagents `task` tool).
567+
from langchain_core.runnables.config import var_child_runnable_config
568+
569+
token = var_child_runnable_config.set(
570+
{"configurable": {"thread_id": "parent", "checkpoint_ns": "p:parent-task"}}
571+
)
572+
try:
573+
merged = ensure_config({"configurable": {"ls_agent_type": "subagent"}})
574+
finally:
575+
var_child_runnable_config.reset(token)
576+
assert merged["configurable"]["ls_agent_type"] == "subagent"
577+
assert merged["configurable"]["checkpoint_ns"] == "p:parent-task"
578+
assert merged["configurable"]["thread_id"] == "parent"
579+
580+
581+
def test_ensure_config_same_thread_id_still_clears_ambient() -> None:
582+
# A child that reuses the parent's thread_id is still addressing its own root
583+
# namespace on that thread, so the parent task's checkpoint_ns must not leak
584+
# in; otherwise the child writes state that get_state cannot read back.
585+
from langchain_core.runnables.config import var_child_runnable_config
586+
587+
token = var_child_runnable_config.set(
588+
{"configurable": {"thread_id": "shared", "checkpoint_ns": "p:parent-task"}}
589+
)
590+
try:
591+
merged = ensure_config({"configurable": {"thread_id": "shared"}})
592+
finally:
593+
var_child_runnable_config.reset(token)
594+
assert merged["configurable"]["thread_id"] == "shared"
595+
assert "checkpoint_ns" not in merged["configurable"]
596+
597+
509598
def test_ensure_config_merges_metadata_across_configs() -> None:
510599
a = {"metadata": {"user_id": "U1"}}
511600
b = {"metadata": {"correlation_id": "C1"}}

0 commit comments

Comments
 (0)