TL;DR

MongoDBSaver in @langchain/langgraph-checkpoint-mongodb saves the entire agent state as one MongoDB document on every step. Once the combined state passes MongoDB’s 16 MB document limit, the run fails. Store each large state channel as its own document and write only the channels that changed.

Context

LangGraph is a framework for building AI agents as graphs. A checkpointer saves the agent’s progress after each step, so a run can resume after a crash, pause for human input, or be rewound (“time travel”).

Concepts used below:

• Channel: a named slot in the agent’s state (for example, a message list or a tool result). A step may change some channels and leave the rest alone.
• Checkpoint: a snapshot of all channels at one step. Each channel has a version that changes only when its value changes.
• 16 MB limit: the maximum size of one MongoDB document. It is fixed and can’t be raised.

The problem: [MongoDBSaver.put|https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint-mongodb/src/checkpoint.ts] serializes the whole checkpoint, every channel’s value, into one document and rewrites all of it each step. It receives the list of changed channel versions (newVersions) but doesn’t use it. So the 16 MB limit applies to the sum of all channels, and unchanged data is rewritten every step. 

Desired User Experience

The code the developer writes doesn’t change. Only what succeeds does

Goals

• A run with large total state works, with the 16 MB limit applying per channel.
• Each step writes only the channels that changed.
• Existing threads keep working after the upgrade with no forced migration.

Where: [libs/checkpoint-mongodb/src/checkpoint.ts|https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint-mongodb/src/checkpoint.ts]

Acceptance Criteria

• The LangGraph checkpointer conformance tests (a minimal version) pass on MongoDB 7.0 and 8.x.
• (Not covered by the suite) The 7 MB + 10 MB example completes and resumes from a fresh saver instance.
• A single channel over 16 MB raises a clear error naming the channel and size, and nothing is written.
• For a 15 MB state with one changing channel, bytes written per step drop by at least half.
• A read never returns partial state: if a stored channel value is missing, it fails with an error.
• Threads created before the upgrade still read and write correctly; new threads use the new layout.
• The stored layout matches the Python saver’s, so both languages behave the same.
• A follow-up ticket exists to update the checkpointer documentation.

Additional Context

• Existing threads keep their original format because mixing old (integer) and new (string) channel versions inside one thread is unsafe.
• A channel that grows without limit will still reach 16 MB eventually. This change makes that failure clear but doesn’t prevent it.
• Reference Solution Doc