LangGraph Checkpoint Base Interfaces

4.0.1 · active · verified Sat Apr 11

LangGraph-checkpoint provides the base interfaces for checkpoint savers within the LangGraph framework (version 4.0.1). It defines the fundamental persistence layer, allowing LangGraph agents to save and restore their state across interactions, which is crucial for features like human-in-the-loop workflows, conversational memory, and time-travel debugging. This library also includes a default in-memory checkpointer for testing and experimentation. It releases frequently, often in conjunction with the main `langgraph` library.

Common errors

```
ModuleNotFoundError: No module named 'langgraph.checkpoint.sqlite'
```
cause Specific checkpointer implementations like `SqliteSaver` or `PostgresSaver` are not part of the base `langgraph-checkpoint` library but are provided by separate, optional packages (`langgraph-checkpoint-sqlite` or `langgraph-checkpoint-postgres`) which need to be installed explicitly.

fix Install the required package, for example: `pip install langgraph-checkpoint-sqlite` or `pip install langgraph-checkpoint-postgres`.
```
MISSING_CHECKPOINTER
```
cause The LangGraph application attempts to use persistence functionality (e.g., saving state) but no checkpointer instance has been provided to the graph's `compile()` method or `@entrypoint` decorator.

fix Instantiate a `BaseCheckpointSaver` (e.g., `InMemorySaver` for development or a production-grade saver like `PostgresSaver`) and pass it to the `compile()` method: `checkpointer = InMemorySaver()` `graph = builder.compile(checkpointer=checkpointer)`.
```
AttributeError: '_GeneratorContextManager' object has no attribute 'get_next_version'
```
cause When using `PostgresSaver.from_conn_string()` (or similar `from_conn_string` methods), it returns a context manager, not the `PostgresSaver` instance itself. Attempting to call methods like `setup()` directly on this context manager will result in an `AttributeError` or `TypeError`.

fix Properly use the context manager with a `with` statement to obtain the actual `PostgresSaver` instance: `with PostgresSaver.from_conn_string(DB_URI) as checkpointer: checkpointer.setup() # Now setup() is called on the actual saver instance`.
```
"DocumentTooLarge" errors during checkpoint saves
```
cause This error typically occurs when using a checkpointer with a backend like MongoDB, which has a 16MB document size limit. Storing large amounts of data or binary objects directly in the graph state can quickly exceed this limit as a new checkpoint is saved at every super-step.

fix Reduce the size of the application state saved to checkpoints, avoid storing large binary data directly in the state (instead, store references to external storage), or consider switching to a database backend like PostgreSQL which supports larger field sizes.

Warnings

breaking The `thread_ts` parameter was renamed to `checkpoint_id` in `langgraph-checkpoint` v1.0.0. While `thread_ts` is currently still recognized, it's deprecated. Update your code to use `checkpoint_id` for clarity and future compatibility.
Fix: Replace `thread_ts` with `checkpoint_id` in your graph configuration (e.g., `{"configurable": {"thread_id": "1", "checkpoint_id": "some_uuid"}}`).
breaking Due to the move to namespace packages, direct imports from top-level `langgraph` modules (e.g., `langgraph.checkpoint`, `langgraph.graph`) are no longer valid. You must use the fully qualified path for the specific sub-module.
Fix: Change import statements from `from langgraph.module import Symbol` to `from langgraph.module.submodule import Symbol` (e.g., `from langgraph.checkpoint.base import BaseCheckpointSaver`, `from langgraph.graph.state import StateGraph`).
gotcha When using any checkpointer, `thread_id` is a mandatory configuration parameter for graph invocations to enable state persistence. Without it, the checkpointer cannot save or retrieve state.
Fix: Always include `{"configurable": {"thread_id": "your_unique_thread_id"}}` in your `graph.invoke()` or `graph.stream()` calls.
gotcha For database-backed checkpointers (e.g., SQLite, PostgreSQL, MySQL), the `.setup()` method must be called on the checkpointer instance to create necessary tables before first use.
Fix: Ensure you call `checkpointer.setup()` (or `await checkpointer.asetup()` for async) after initializing a database checkpointer.
gotcha In `langgraph-checkpoint-postgres` versions 2.0.22 and higher, metadata serialization changed. Non-JSON serializable objects (e.g., `HumanMessage` instances directly) stored in checkpoint metadata will now raise errors, as metadata is passed as JSONB.
Fix: Ensure that any objects stored in checkpoint metadata are JSON serializable. Convert complex Python objects to their JSON-compatible representations before storing them, or move non-JSON data to dedicated channel blobs.
breaking Security vulnerabilities (CVE-2026-28277 for unsafe msgpack deserialization and CVE-2026-27022 for Redis query injection) have been disclosed impacting LangGraph's checkpoint system for certain backend implementations. These can lead to remote code execution or query injection.
Fix: Immediately update to the latest versions of `langgraph-checkpoint` and any specific `langgraph-checkpoint-*` backend libraries you are using. Review your usage of community-contributed checkpointers for similar vulnerabilities.

Install

pip install langgraph-checkpoint Install base library

Imports

BaseCheckpointSaver
wrong:
```
from langgraph.checkpoint import BaseCheckpointSaver
```
correct:
```
from langgraph.checkpoint.base import BaseCheckpointSaver
```
Due to the transition to namespace packages, direct re-exported imports from `langgraph.checkpoint` are no longer supported since LangGraph v0.2 / langgraph-checkpoint v1.0.0.
InMemorySaver
```
from langgraph.checkpoint.memory import InMemorySaver
```
The in-memory saver is provided for development and testing.
JsonPlusSerializer
```
from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
```
The default serializer for checkpoint data, handling various Python types.

Quickstart

This quickstart demonstrates how to set up a basic `StateGraph` and configure it with the `InMemorySaver` from `langgraph-checkpoint`. The `InMemorySaver` is suitable for local development and testing, saving state in memory. For persistent storage, you would typically use an external checkpointer like `PostgresSaver` or `SqliteSaver` from their respective `langgraph-checkpoint-*` libraries.

import os
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver

# Define the state for the graph
class AgentState(TypedDict):
    messages: list[str]

# Define a simple node
def chat_node(state: AgentState) -> AgentState:
    # In a real agent, this would involve LLM calls or tool execution
    print(f"Processing: {state['messages'][-1]}")
    new_message = f"Echo: {state['messages'][-1]}"
    return {"messages": state["messages"] + [new_message]}

# Build the graph
builder = StateGraph(AgentState)
builder.add_node("echo_chat", chat_node)
builder.add_edge(START, "echo_chat")
builder.add_edge("echo_chat", END)

# Initialize the in-memory checkpointer
checkpointer = InMemorySaver()

# Compile the graph with the checkpointer
# A real LangGraph application would likely use a more complex graph and invoke it
# to test persistence.
# For this quickstart, we just demonstrate setup.
graph = builder.compile(checkpointer=checkpointer)

# Example of how you would invoke (not part of langgraph-checkpoint itself, but for context)
# config = {"configurable": {"thread_id": "1"}}
# inputs = {"messages": ["Hello LangGraph!"]}
# result = graph.invoke(inputs, config=config)
# print(result)

view raw JSON →