LangGraph Checkpoint Base Interfaces

raw JSON →
4.0.1 verified Tue May 12 auth: no python install: verified quickstart: stale

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.

pip install langgraph-checkpoint

Common errors

error 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.
error 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).
error 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.
error "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 compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 1.26s 64.8M
3.10 alpine (musl) - - 1.29s 63.9M
3.10 slim (glibc) wheel 7.9s 0.91s 73M
3.10 slim (glibc) - - 0.89s 72M
3.11 alpine (musl) wheel - 1.57s 70.1M
3.11 alpine (musl) - - 1.75s 69.1M
3.11 slim (glibc) wheel 6.7s 1.36s 78M
3.11 slim (glibc) - - 1.31s 77M
3.12 alpine (musl) wheel - 1.72s 61.1M
3.12 alpine (musl) - - 1.78s 60.1M
3.12 slim (glibc) wheel 5.5s 1.63s 69M
3.12 slim (glibc) - - 1.68s 68M
3.13 alpine (musl) wheel - 1.51s 60.9M
3.13 alpine (musl) - - 1.60s 59.7M
3.13 slim (glibc) wheel 5.7s 1.49s 69M
3.13 slim (glibc) - - 1.59s 68M
3.9 alpine (musl) wheel - 1.59s 61.4M
3.9 alpine (musl) - - 1.56s 61.4M
3.9 slim (glibc) wheel 8.3s 1.51s 69M
3.9 slim (glibc) - - 1.34s 69M

Imports

Quickstart stale last tested: 2026-04-24

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)
last verified Tue May 12
next check Sat Jun 27