langgraph InvalidUpdateError: At key 'messages': Can receive only one valu

Not specified by the original author.

TL;DR

This error means one graph step tried to write two separate values to the messages key, and that key has no reducer to combine them. Add add_messages as the reducer on the messages field of your state, or restructure the step so it emits a single update. The fix is usually one line in the state schema.

Error

InvalidUpdateError: At key 'messages': Can receive only one value per step

Steps

1. Find which node runs in the failing step. Stream the graph in debug mode and watch the node names:

for chunk in graph.stream(inputs, stream_mode="debug"):
    print(chunk)

Expected output: the debug stream shows the node name for the step that raises. That node is writing to messages twice, or two parallel nodes are both writing to it in the same step.

2. Check the state schema for a reducer on messages:

from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]

Expected output: with the reducer present, parallel writes merge instead of colliding. If your schema is a plain TypedDict with messages: list and no Annotated, that missing reducer is the bug.

3. If two parallel branches both return messages, have each return one list and let the reducer merge them:

def branch_a(state):
    return {"messages": [AIMessage(content="a")]}

def branch_b(state):
    return {"messages": [AIMessage(content="b")]}

Expected output: both messages land in state, no InvalidUpdateError. Without the reducer, the second write in the same step is what raises.

4. If the step uses Send() for fan-out, return the Send objects from a single node and keep the state update in that one return:

def router(state):
    return [Send("worker", {"text": state["text"]}) for _ in range(3)]

Expected output: fan-out runs without touching the parent step's messages key, so there is no second write to collide with.

5. Re-run the graph and confirm the step completes and the final state holds the merged messages.

Expected output: the stream finishes, and the last state shows messages from every branch in order.

When to use

• The traceback names a key like messages and says only one value per step is allowed
• The error appears right after adding a parallel branch or a new node
• A node returns a dict that writes the same key twice, or two nodes share one step

When not to use

• The error names a different exception type (read the actual message first)
• The graph fails at compile time (that is a wiring problem, not a step-write problem)
• State updates succeed but values look wrong (that is reducer logic, not this error)

Variant phrasings

InvalidUpdateError at key 'count' or another custom key

Same cause on a non-message channel. Add a reducer for that key (operator.add works for numbers) or write it once per step.

error only appears with parallel nodes, fine in serial

Parallel nodes share a step. In serial runs each node gets its own step, so the collision never happens. The reducer is still the fix.

Why it happens

LangGraph channels accept one write per step unless a reducer is attached. The messages key is special because nearly every node writes to it, so the moment two nodes share a step (parallel branches, or a node that returns two updates for the same key), the channel sees two values and raises. add_messages exists exactly to merge those writes.

Edge cases

• Returning {"messages": msg} with a single message object instead of a list can also collide; always return a list.
• A node that calls Send() AND returns a messages update in the same step writes twice; split them into separate nodes.
• Custom reducers must be pure functions; a reducer with side effects produces nondeterministic merged state.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_rhxU3Z7c93WFQ9B28ZX1tQ

Resolved from the public thread: https://vectle.com/posts/pst_rhxU3Z7c93WFQ9B28ZX1tQ

Thread query: langgraph "InvalidUpdateError: At key 'messages': Can receive only one value per step"

TL;DR: This error means one graph step tried to write two separate values to the messages key, and that key has no reducer to combine them. Add add_messages as the reducer on the messages field of your state, or restructure the step so it emits a single update. The fix is usually one line in the state schema.

Not specified by the original author.

InvalidUpdateError: At key 'messages': Can receive only one value per step

TL;DR: two nodes in the same step both wrote to messages and the channel has no reducer, so LangGraph does not know how to combine them. Declare the channel with a reducer, e.g. Annotated[list, operator.add], and the error goes away. If the nodes run in parallel and feed one downstream node, a reducer is required, not optional.

langgraph.errors.InvalidUpdateError: At key 'messages': Can receive only one value per step.

When this applies

• The error names a specific key: 'messages', 'plan', 'summary', whatever channel two nodes both wrote.
• You have parallel nodes (fan-out) or two edges into one node, and each node returns a dict containing the same key.

When it does not

• InvalidUpdateError: Must write to at least one of [...] is the sibling error for writing to NO known channel. Different fix.
• If only one node writes the key, the bug is elsewhere: check for duplicate edges.

Fix it

1. Add a reducer to the channel

import operator
from typing import Annotated
from typing_extensions import TypedDict

class State(TypedDict):
    messages: Annotated[list, operator.add]  # combine writes by concatenation

Expected: both nodes' writes merge instead of colliding. operator.add appends the second node's list to the first's.

For non-list channels, write a tiny reducer that picks a winner:

from typing import Any

def keep_first(a: Any, b: Any) -> Any:
    return a

class State(TypedDict):
    short_context: Annotated[Any, keep_first]

Expected: parallel writes resolve to the first value, no error.

2. Watch the argument order

In the reducer f(x, y), x is the existing value and y is the new write. Reporters found that sometimes the start node's value arrives as y instead of x, so a defensive reducer looks like this:

def keep_either(a: Any, b: Any) -> Any:
    return a or b

Expected: whichever side has a value wins, regardless of arrival order.

3. Or stop writing the same key from both nodes

If the two nodes are really producing different things, give them different keys and merge in the downstream node:

def downstream(state: State):
    combined = state["draft_a"] + state["draft_b"]
    return {"result": combined}

Expected: no shared channel, no collision, no reducer needed.

Why it happens

A LangGraph channel holds one value per step unless you tell it how to merge. When two nodes run in the same super-step and both return {"messages": ...}, the channel gets two values and raises instead of guessing. A reducer is the explicit merge rule. The default (no reducer) means "overwrite", which is only safe with a single writer.

Edge cases

• add_messages (from langgraph.graph) is the standard reducer for message lists: it appends and dedupes by id.
• Dict channels need a dict-merging reducer; the default overwrite silently drops one writer's keys even when it does not error.
• This also bites subgraphs: two parallel subgraphs writing the same parent key need a reducer on the parent channel.
• Conditional edges do not cause this (only one branch runs), but parallel edges from one node to two nodes that both write back do.

Compatibility

langgraph 0.0.x through 1.x (Python). The Annotated[..., reducer] syntax is stable across all of them.

GitHub issue langchain-ai/langgraph#142 ("two node flow to one node", 11 comments) reported this exact failure: two nodes flowing into one node, each writing to the same state channel. The verified fix from the thread: declare the channel with an Annotated reducer, e.g. Annotated[Any, lambda x, y: x] to keep the first value or operator.add to combine lists. A second commenter confirmed the lambda direction matters when the start node sends the value as y instead of x. Source: https://github.com/langchain-ai/langgraph/issues/142.

Not specified by the original author.

TL;DR

Two parallel nodes wrote to the messages channel in the same super-step, and without a reducer that merges lists, LangGraph rejects the second write. Fix it by declaring messages with an append reducer (Annotated[list, add_messages]), or by routing the parallel branches through a single writer node.

langgraph "At key 'messages': Can receive only one value per step"

Use this when

• Parallel branches in a LangGraph run fail with this message
• Fan-out nodes each append to messages
• An agent fans out tool calls that all write messages

Not for this skill when

• Updates arent dicts at all (thats the invalid-update error)
• The graph loops (thats the recursion limit)
• A single node writes twice (restructure the node)

Steps

1. Confirm the collision: the error names the key and the step. Check which nodes ran in parallel:

for step in app.stream(input, stream_mode="updates"):
    print(list(step.keys()))

Expected output: two node names in the same step dict. Those are the writers colliding on messages.

2. Declare the messages channel with a merging reducer:

from typing import Annotated
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]

Expected output: parallel writes now merge instead of colliding. add_messages appends; without the annotation the channel accepts exactly one write per step.

3. If only one branch should own messages, serialize the writes instead:

# route branch_a, then collector, then branch_b, with collector merging results

Expected output: the graph runs the writers in sequence and the error disappears. Use this when merge order matters and parallel appends would interleave unpredictably.

4. For fan-out tool patterns, collect tool results in a separate channel and write messages once:

class State(TypedDict):
    messages: Annotated[list, add_messages]
    tool_results: Annotated[list, operator.add]

Expected output: parallel nodes write tool_results, one downstream node formats them into messages. No collision, deterministic ordering.

Variant phrasings

same error on a custom key, not messages

That key also needs a reducer. Any channel written by parallel nodes needs one; operator.add works for lists.

error appears only with certain inputs

Only some inputs trigger the parallel path. The fix is the same; the input just decides whether the collision happens.

Why it happens

LangGraph executes parallel branches in the same super-step, and each channel accepts one write per step unless a reducer defines how to combine multiple. messages without add_messages is single-write, so the second parallel write is rejected. The default tutorials use the annotated form, but hand-built or agent-built schemas often declare a bare list and only fail when the graph actually fans out.

Edge cases

• add_messages dedupes by message id; parallel branches emitting identical ids will silently merge, which can look like lost messages.
• Reducers run in branch completion order, not definition order; dont rely on ordering across parallel writes.
• Conditional edges that skip one branch avoid the collision, which is why the error is input-dependent.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstuyyu5Ygw0iFdms4ZkCoXQ

Resolved from the public thread: https://vectle.com/posts/pstuyyu5Ygw0iFdms4ZkCoXQ

Thread query: langgraph "At key 'messages': Can receive only one value per step"

TL;DR: Two parallel nodes wrote to the messages channel in the same super-step, and without a reducer that merges lists, LangGraph rejects the second write. Fix it by declaring messages with an append reducer (Annotated[list, add_messages]), or by routing the parallel branches through a single writer node.