langgraph "MessageGraph" deprecated: migrate to StateGraph with messages key

Not specified by the original author.

TL;DR

MessageGraph is deprecated; the replacement is StateGraph with a messages key in the state. Swap the constructor, declare the state with an add_messages reducer, and keep your nodes and edges as they are.

Error

LangGraphDeprecationWarning: MessageGraph is deprecated. Please use StateGraph with a messages key instead.

Steps

1. Declare a state schema with a messages key using the add_messages reducer:

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: a state type that appends messages instead of overwriting them, matching old MessageGraph behavior.

2. Replace the MessageGraph constructor with StateGraph carrying that state:

# before
# graph = MessageGraph()
from langgraph.graph import StateGraph
builder = StateGraph(State)

Expected output: no deprecation warning on construction.

3. Port the nodes. MessageGraph nodes received a message list; StateGraph nodes receive the state dict and return a messages update:

def my_node(state: State):
    reply = llm.invoke(state["messages"])
    return {"messages": [reply]}

Expected output: each node appends its reply to the running message list, exactly like before.

4. Wire entry point and edges the same way, then compile and run a parity test:

builder.add_node("my_node", my_node)
builder.set_entry_point("my_node")
builder.set_finish_point("my_node")
graph = builder.compile()

Expected output: identical conversation output to the old MessageGraph, with no deprecation warning.

When to use

• Your code constructs MessageGraph anywhere
• You are upgrading LangGraph and the warning appears in logs
• A tutorial or older codebase you inherited uses MessageGraph

When not to use

• You need custom state fields beyond messages (declare a fuller TypedDict on StateGraph, this migration is just the starting point)
• You are writing a new graph from scratch (start on StateGraph directly)
• You pinned an old LangGraph and cannot upgrade (the warning is harmless until you do)

Variant phrasings

"MessageGraph is deprecated, use StateGraph" import warning

Same migration. The warning fires at import or construction time depending on version.

migrating a message-only subgraph

Apply the same swap inside the subgraph builder, then compile it and add it to the parent as a single node.

Why it happens

MessageGraph was always a thin wrapper around StateGraph with a pre-filled messages state. The maintainers deprecated the wrapper to keep one code path, so the messages-key pattern is now the canonical way to get the same behavior.

Edge cases

• Nodes that returned a bare message must now return {"messages": [...]}; a bare return silently drops the reply.
• add_messages lives in langgraph.graph.message; importing it from elsewhere breaks on newer versions.
• set_entry_point/set_finish_point still exist on StateGraph, so simple linear chains port with no edge changes.

Provenance

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

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

Thread query: langgraph "MessageGraph" deprecated: migrate to StateGraph with messages key

TL;DR: MessageGraph is deprecated; the replacement is StateGraph with a messages key in the state. Swap the constructor, declare the state with an add_messages reducer, and keep your nodes and edges as they are.

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.

TL;DR

Every node in a LangGraph graph must return a state update that touches at least one channel in the graph's state schema. This error means some node returned None, an empty dict, or only keys the graph does not know about. Find the node whose return value misses the state schema and make every branch return at least one valid state key.

The error

must write to at least one of [] langgraph

The full form names the channels the engine expected:

langgraph.errors.InvalidUpdateError: Must write to at least one of ['messages']

The list in brackets is your checklist - the node's return value has to include at least one of those keys.

Steps

1. Read the channel list in the error message

Copy the list from inside the brackets. Those are the state channels the failing node was required to write to.

Expected: you have a concrete list of keys, like ['messages'] or ['input', 'plan', 'response'].

2. Find which node produced the bad write

Run the graph with a small input and print what each node returns. The culprit is usually a routing or conditional node:

def debug_node(state):
    result = real_node(state)
    print("node returned:", result)
    return result

Expected: you spot the node returning None, {}, or a dict whose keys are not in your state schema.

3. Make every branch return a state key

The most common cause is a conditional node that forgets to return a payload on one branch. Even a no-op branch must return something valid:

def router(state):
    if should_skip(state):
        return {"messages": []}
    return {"messages": [do_work(state)]}

Expected: every branch returns a dict containing at least one key from the state schema.

4. Check subgraph and Send-based nodes against the parent schema

If a node runs inside a subgraph or is triggered by a Send, its return value is validated against the graph it writes to, not its own private state. Returning only private keys the parent graph does not declare raises this exact error. Either return keys the parent state declares, or declare the private shape with the output argument:

graph = StateGraph(State, output=PrivateState)

Expected: the subgraph node writes keys the parent graph accepts, and the error stops.

5. Re-run and confirm the graph completes

Invoke the graph with the same input that failed.

Expected: no InvalidUpdateError, and the final state contains the updates the nodes produced.

Use this when

• A LangGraph run raises InvalidUpdateError: Must write to at least one of [...]
• A conditional routing node returns None or an empty dict on some branch
• A subgraph node returns private-state keys the parent graph schema does not declare
• A Send-triggered node writes keys outside the graph's state channels

Not for this skill when

• The error is At key 'X': Can receive only one value per step - that is concurrent writes to one channel without a reducer, a different problem
• The graph runs but produces wrong results - that is a logic bug, not a write-validation failure
• The failure is a tool-calling or model error inside the node, before any state write happens

Variant phrasings

InvalidUpdateError: Must write to at least one of ['input', 'plan', 'past_steps', 'response']

Same error with a multi-channel state. The fix is identical: the node's return must overlap with at least one listed key.

Node returned None in langgraph

The most common concrete trigger. A node that implicitly returns None (no return statement, or a branch that falls through) fails the write check.

PrivateState not working with Send in langgraph

The subgraph variant: a node activated by Send returns its private keys, but the graph validates against the parent state schema. Return parent-schema keys or set the graph's output shape.

Why it happens

LangGraph's Pregel runtime validates every node's output before merging it into the state channels. A node's return dict is intersected with the declared state channels; if the intersection is empty, the engine refuses to proceed rather than silently dropping the write, because an empty write usually means the node forgot to produce its result. The strictness is deliberate - it turns a silent no-op into a loud, fixable error.

Edge cases

• Older langgraph versions reject an explicit empty patch {}: if every component legitimately returns {} by design, upgrade langgraph to the pinned version instead of restructuring your nodes.
• Reducers and None: a channel with a reducer may tolerate None in some configurations, but an explicit None return still fails validation in others. Return the key explicitly rather than relying on reducer leniency.
• Conditional edges pointing at removed nodes: after refactoring the state schema or renaming nodes, a route name may no longer exist. The error then appears at the routing node - re-check the edge map.
• Skip flags: prefer returning an explicit empty-but-valid update (like {"messages": []}) over returning nothing when a node intentionally does no work.

Provenance

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

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

Thread query: must write to at least one of [] langgraph

TL;DR: Every node in a LangGraph graph must return a state update that touches at least one channel in the graph's state schema. This error means some node returned None, an empty dict, or only keys the graph does not know about. Find the node whose return value misses the state schema and make every branch return at least one valid state key.