StateGraph, state, and reducers
A StateGraph node returns a partial update, and each state key merges that update with its reducer, or replaces the old value when the key has no reducer.
You write a graph in which three nodes run in the same step, and each one adds a joke to a list. One version of the graph ends with three jokes. Another version raises an error before the step ends. What decides it is the reducer of the key that the nodes write.
When you finish this section, you can declare a state schema and choose a reducer for each key. You can also predict what two writes to one key in one step do.
The state schema
State: the shared data of one graph run, declared as a schema whose keys are the values that nodes read and write.
Reducer: a function of the old value and an update that returns the new value of one state key.
create_agent built its graph for you in Part 1. A StateGraph is the same object, and you build it by hand. The kit declares its state as a TypedDict. Two keys carry a reducer in Annotated, and three keys have none:
class Fanout(TypedDict):
topic: str
subjects: list[str]
jokes: Annotated[list[str], operator.add]
log: Annotated[list[str], operator.add]
best: strA key with no reducer keeps the last value written to it. The graph API page states this default too, and it adds that a node returns only the keys it changes. LangGraph stores such a key in a LastValue channel, and a key with a reducer in a BinaryOperatorAggregate channel. A schema can also be a dataclass or a Pydantic model, but create_agent needs a TypedDict.
A node returns a partial update
A node is a function of the state. It returns a dict with only the keys it changes. The first node of the kit graph writes two of the five keys:
def plan(state):
return {"subjects": ["cats", "dogs", "owls"], "log": ["plan"]}LangGraph applies each key of the update with the reducer of that key. subjects has no reducer, so the list replaces the empty list of the input. log has operator.add, so ["plan"] joins the end of the old list. Every node after it adds one entry to log in the same way.
The run ends with six entries in log, one for each node run:
"jokes": [
"a joke about cats",
"a joke about dogs",
"a joke about owls"
],
"log": [
"plan",
"write_joke(cats)",
"write_joke(dogs)",
"write_joke(owls)",
"pick -> publish",
"publish"
],
"best": "a joke about cats"Two writes to one key in one step
The three write_joke runs happen in one step, and each returns one joke under jokes. The reducer joins the three updates, so the state holds three jokes. Section 6.2 shows how the graph starts three runs of one node.
A key with no reducer accepts one write in each step. The kit builds a graph whose two nodes both start after __start__, and both write value:
class Plain(TypedDict):
value: str
g = StateGraph(Plain)
g.add_node("a", lambda s: {"value": "a"})
g.add_node("b", lambda s: {"value": "b"})
g.add_edge(START, "a")
g.add_edge(START, "b")The run raises at the end of the step, and the error names the key:
raised langgraph.errors.InvalidUpdateError: At key 'value': Can receive only one value per step. Use an Annotated key to handle multiple values.
For troubleshooting, visit: https://docs.langchain.com/oss/python/langgraph/errors/INVALID_CONCURRENT_GRAPH_UPDATEFigure 6.1 sets the two keys side by side.
The joined list keeps the order of the three subjects: cats, dogs, owls. The kit check records that order again on every run.
What the error leaves in a saved thread
On a graph with a checkpointer, the error does more than fail one run. Both node bodies ran before the update raised, and both writes were saved as pending writes. Every later read of the thread applies those writes again, and raises again.
The runtime part ran the two-node graph with a checkpointer, InMemorySaver. Each node asked Qwen3 4B for a digit and returned it as x, on the x86 server guest:
raised InvalidUpdateError: At key 'x': Can receive only one value per step. Use an Annotated key to handle multiple values.
…
node bodies that ran before the raise: ['a', 'b']
…
get_state after the raise ALSO raises InvalidUpdateError via ['main.py:1496', 'main.py:1331', '_algo.py:319', 'last_value.py:64']
…
raw saver.get_tuple works: checkpoint step=0 pending_writes=[('26351ed0', 'x', 1), ('8f6a50fe', 'x', 2)]
…
invoke(None) resume raises again: InvalidUpdateError; node bodies re-run on resume: [] (empty means the saved writes were reapplied, not re-executed)So get_state raises, and an admin page that reads the thread fails too. invoke(None) raises without running a node. A new turn on the same thread raises as well. Only get_state_history and the raw saver still read the thread. We reported this as langgraph issue #9712. Section 2.2 follows the raise through the update phase.
Recovering the thread
We measured four ways out on the x86 server guest with Qwen3 4B, one run each, on the same graph: Raw runs
## 1. same graph, after the raise
get_state: raises InvalidUpdateError: At key 'x': Can receive only one value per step. Use an Annotated key to handle multiple v
update_state(cfg, {'x': 9}): ok -> {'configurable': {'thread_id': 't1', 'checkpoint_ns': '', …
invoke(None): raises InvalidUpdateError: At key 'x': Can receive only one value per step. Use an Annotated key to handle multiple v
node bodies run by invoke(None): ['a', 'b']; model calls so far 4
invoke({'x': 5}) as a new turn: raises InvalidUpdateError: At key 'x': Can receive only one value per step. Use an Annotated key to handle multiple v
## 2. same saver, graph recompiled with x: Annotated[int, operator.add]
get_state: ok -> {'x': 3}
invoke(None): ok -> {'x': 3}
node bodies run by invoke(None): []; model calls so far 8- A reducer repairs the thread from its saved writes. The same saver, under a graph with
x: Annotated[int, operator.add], read the thread at once and finished the run. No node ran again, so no model call was paid twice. The value was 3, the input 0 plus 1 plus 2. update_staterecovers the thread too. It writes a new checkpoint with the value you pass, and the repro of issue #9712 reads the thread again after it. The graph is still wrong, though. The nextinvoke(None)ran both nodes and both model calls again, and raised again.- A fork from the input checkpoint, under the same graph, ran both nodes and raised.
delete_threadclears the thread, and you lose its history.
So deploy the reducer first. Every broken thread then finishes from its saved writes. Use update_state when you must set the value by hand, and only on a graph that has the reducer. Choose the reducer for what the key means, because it decides the value of the repaired thread.
add_messages and MessagesState
add_messages: the reducer for a list of messages. It appends a message with a new id, replaces a message with the same id, and deletes the message that a RemoveMessage names.
The kit calls add_messages on two messages m1 and m2. An update with a new text for m2 and a new message m3 replaced one and appended the other. An update with RemoveMessage(id="m1") left only m2:
replace m2, append m3:
…
"content": "first",
"id": "m1"
…
"content": "second, edited",
"id": "m2"
…
"content": "third",
"id": "m3"
…
remove m1:
[
{
"type": "HumanMessage",
"content": "second",
"id": "m2"
}
]So the messages key of an agent can change in place. The agents page calls it append only, and the short-term memory page removes messages with RemoveMessage. The code of add_messages decides, and this manual records the disagreement as conflict D104.
MessagesState is a schema with one messages key and the add_messages reducer. A node can return a dict such as {"role": "assistant", "content": "..."}, and the reducer turns it into an AIMessage with a new UUID. Every message in the state then has an id, so a later update can replace or remove it.
Clearing a key that has a reducer
A node that returns an empty list for log does not clear it, because operator.add joins the empty list to the old one. The state page says to wrap the value in Overwrite to skip the reducer. The kit does not run Overwrite yet. A capture of it comes in the next edition, with the other open items of section 8.8.
LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0 · c2f4036 · 2026-11-11 · Edition 2026.11