Registry /
llm-agents / langgraph-checkpoint-mongodb
Install & Compatibility
Where this runs
tested against v0.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.392s · 196.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 14.3s · import 1.300s · 199MB
202MB installed
● package 202MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MongoDBSaver
✓ from langgraph.checkpoint.mongodb import MongoDBSaver
This quickstart demonstrates how to initialize `MongoDBSaver` and interact with it directly to save and load a dummy checkpoint. In a typical LangGraph application, the `checkpointer` instance is passed to the `graph.compile()` method to automatically manage state persistence.
import os
from langgraph.checkpoint.mongodb import MongoDBSaver
from pymongo import MongoClient
# NOTE: Ensure a MongoDB instance is running, e.g., locally at mongodb://localhost:27017
# Replace with your actual MongoDB URI
MONGODB_URI = os.environ.get('MONGODB_URI', 'mongodb://localhost:27017')
DB_NAME = "langgraph_checkpoints_db"
COLLECTION_NAME = "checkpoints_collection"
# Initialize the MongoDB client
client = MongoClient(MONGODB_URI)
# Initialize the checkpointer with a client, database name, and optional collection name
checkpointer = MongoDBSaver(
client,
db_name=DB_NAME,
collection_name=COLLECTION_NAME
)
# Example usage with a dummy checkpoint and config (simplified for quickstart)
# In a real LangGraph application, this would be managed by the graph's execution.
config = {"configurable": {"thread_id": "test_thread_1", "checkpoint_ns": ""}}
dummy_checkpoint = {
"v": 1,
"ts": "2026-04-11T12:00:00.000000+00:00",
"id": "12345678-abcd-1234-abcd-1234567890ab",
"channel_values": {"my_state": "initial_value"},
"channel_versions": {},
"versions_seen": {},
"pending_sends": []
}
print(f"Saving checkpoint for thread_id: {config['configurable']['thread_id']}")
checkpointer.put(config, dummy_checkpoint, {}, {})
print("Checkpoint saved.")
print(f"Loading checkpoint for thread_id: {config['configurable']['thread_id']}")
loaded_checkpoint_tuple = checkpointer.get(config)
if loaded_checkpoint_tuple:
print(f"Loaded checkpoint state: {loaded_checkpoint_tuple.checkpoint.channel_values}")
else:
print("No checkpoint found.")
# Clean up (optional, for demonstration)
checkpointer.delete_thread(config)
print(f"Deleted checkpoints for thread_id: {config['configurable']['thread_id']}")
client.close()
Debug
Known issues
breakingBreaking changes in the base `langgraph-checkpoint` library (e.g., between v0.x/v1.x and v2.x/v3.x) can lead to API mismatches and dependency conflicts. Ensure your `langgraph-checkpoint-mongodb` version is compatible with your `langgraph` and `langgraph-checkpoint` versions to avoid issues like the `langgraph-checkpoint@3.0` incompatibility reported previously.fixRefer to the official documentation and release notes of `langgraph-checkpoint-mongodb` and `langgraph` for compatible version ranges. Upgrade both `langgraph` and `langgraph-checkpoint-mongodb` to their latest compatible versions.
affects: <0.3.1 (possibly previous major `langgraph-checkpoint` versions)
gotchaThe `MongoDBSaver` currently does not offer built-in mechanisms for automatic checkpoint retention or Time-To-Live (TTL) configuration. This means that checkpoints will accumulate indefinitely, potentially leading to significant storage growth in production environments with high conversation volume.fixImplement a periodic cleanup job to manually prune old checkpoints based on `checkpoint_id` (which is time-sortable) or wrap the saver to add an `expiresAt`/`createdAt` top-level field for MongoDB's native TTL indexing. It is recommended to keep at least the last few checkpoints per thread.
affects: All versions up to 0.3.1
gotchaFor use with the official LangGraph Agent Server, a MongoDB replica set is a prerequisite; standalone `mongod` instances are not supported. Additionally, the MongoDB connection URI must include the database name in its path (e.g., `mongodb://localhost:27017/mydatabase`).fixEnsure your MongoDB deployment is a replica set (or Atlas/`mongos` router). Update your MongoDB connection URI to include the database name, for example, `mongodb://<host>:<port>/<db_name>`.
affects: All versions
deprecatedThe `AsyncMongoDBSaver` class has been removed. Users who previously relied on this for asynchronous operations will need to refactor their code to use the main `MongoDBSaver` which handles operations synchronously or manage async interaction at a higher level.fixMigrate from `AsyncMongoDBSaver` to `MongoDBSaver`. Review LangGraph's asynchronous execution patterns to integrate the synchronous `MongoDBSaver` appropriately, potentially by running operations in a separate thread/executor if truly non-blocking database calls are required.
affects: >=0.3.0 (removed around this version)
Errors
Common errors & fixes
DocumentTooLarge: BSON document size XXXX bytes, maximum 16777216
The LangGraph state being saved to MongoDB exceeds MongoDB's strict 16MB BSON document size limit.
fixReduce the size of your LangGraph state by trimming conversation history, summarizing large data objects, or storing large payloads in external storage and only saving references in the state. Consider switching to PostgreSQL if large state objects are unavoidable.
TypeError: Object of type ObjectId is not JSON serializable
The default serializer used by `langgraph-checkpoint-mongodb` (which internally uses `msgpack` or `jsonplus`) does not know how to serialize `bson.ObjectId` instances when they are part of the LangGraph state.
fixConvert `ObjectId` objects to strings (e.g., `str(obj_id)`) when they are added to or retrieved from the LangGraph state, typically within your graph nodes. Alternatively, implement a custom serializer to handle `ObjectId` types.
ERROR: Cannot install langgraph==3.0.0 because langgraph-checkpoint-mongodb requires langgraph<3.0
The `langgraph-checkpoint-mongodb` package (specifically versions around 0.3.1 and earlier) has a dependency constraint that prevents it from being used with `langgraph` versions 3.0.0 or higher, leading to dependency conflicts during installation or upgrade.
AttributeError: 'JsonPlusSerializer' object has no attribute 'dumps'
There is an API mismatch where LangGraph's checkpoint serialization code expects a `dumps()` method on the `JsonPlusSerializer` instance, but this method is missing or has been renamed/refactored in the version of `JsonPlusSerializer` being used.
ModuleNotFoundError: No module named 'langgraph.checkpoint.mongodb'
The `MongoDBSaver` class is incorrectly imported, often due to a misunderstanding of the package structure or a typo in the import statement.
fixEnsure you are importing `MongoDBSaver` directly from `langgraph.checkpoint.mongodb`. The correct import is `from langgraph.checkpoint.mongodb import MongoDBSaver`.
Upgrade
Version history
0.4.0latest on PyPI · released May 12, 2026
Audit
Dependencies
langgraph-checkpointrequiredProvides the base interface for checkpoint saving that this library implements.
pymongorequiredOfficial MongoDB driver for Python, used for database interaction.