Walk through LangGraph time travel debugging via the checkpointer

Short answer·Hard·4.0 · 0·~3 min·Asked atPhonepe Rephrase Ai Salesforce

Attempt it

An agent built on LangGraph produced a bad final answer on thread `t-42`. The checkpointer is configured (Postgres). Walk through how you would use time travel to find the bad decision, edit state at that point, and replay forward from there.

Free · 2 AI evals / day

**LangGraph time-travel** works in five steps when a checkpointer is configured. 1. **List history.** Call `graph.get_state_history({'configurable': {'thread_id': 't-42'}})`. You get every checkpoint along the run, one per node execution, each with a `config` (containing a unique `checkpoint_id`), the name of the node that just ran, and the full state at that point. 2. **Inspect.** Scroll newest to oldest and find the first checkpoint whose state shows the bad decision. Wrong tool arguments, wrong route, missing field. Note its `checkpoint_id`. 3. **Fork by editing.** Call `graph.update_state(config={'configurable': {'thread_id': 't-42', 'checkpoint_id': '<that id>'}}, values={...corrected fields...})`. Pinning the `checkpoint_id` is what makes this a fork. Without it, you would mutate the latest state instead of branching. 4. **Replay.** Invoke the graph again with the config returned by `update_state`. The runtime picks up at the next node from the corrected state and runs forward. 5. **Compare.** Both timelines are persisted by thread plus checkpoint_id, so you can diff outputs between the original and the forked run. Without the checkpointer, none of this works. There are no snapshots to rewind to.

**Time-travel debugging** in LangGraph uses three APIs and one operational discipline. **Three APIs.** 1. `get_state_history(config)`. Lists every checkpoint for a thread, each with its `checkpoint_id`, the node that produced it, and the full state. 2. `update_state(config, values)`. Writes new state. The behaviour depends on whether the config pins a `checkpoint_id`: without one, it mutates the latest; with one, it forks a new branch off that point. 3. Invoke the graph again with the returned config. The runtime resumes at the next node from the corrected state. **The disciplined workflow for thread `t-42`.** - List the history; identify the earliest checkpoint where state diverges from what you expected. - Note that checkpoint's `checkpoint_id`. - Call `update_state` with `{'thread_id': 't-42', 'checkpoint_id': '<that id>'}` and the corrected values. This forks a branch. - Re-invoke the graph with the returned config; it picks up at the next node and runs forward on the corrected state. - Diff the forked run against the original; both are persisted by thread plus checkpoint_id. **Why it works.** The checkpointer (Postgres in your case, also SQLite or in-memory for tests) writes a snapshot after every node. The graph runtime treats state as immutable per checkpoint and treats `update_state` with a pinned id as 'fork from here.' Without the checkpointer, an `AgentExecutor`-style loop is an in-memory while-loop with no snapshots, and time-travel is impossible.

TL;DR

List checkpoints with `get_state_history`, find the bad one, fork by calling `update_state` with a pinned `checkpoint_id`, then re-invoke the graph to replay forward.

Memory aid

Easy to grasp

Picture a video game with auto-saves at every save point. Your character makes a wrong turn at level 4 and dies at level 7. You scroll the save list, pick the save just before the wrong turn, change the equipment in your inventory, and press resume. The game keeps both timelines on disk so you can compare endings. LangGraph plus a checkpointer works the same way. Every node creates a save point. You can list them, edit the saved state at any point, and resume from there. And the original timeline stays intact for comparison.

Key concepts

LLM Frameworks Agents

Concept explanation~2 min read

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.

Debugging an agent that produced a bad final answer used to be log archaeology. You scrolled stdout, hoped you had captured intermediate state, and reconstructed what happened from prompt and response pairs. If you wanted to try a different action at step 4, you re-ran the whole thing from scratch and hoped the model was deterministic enough to reproduce.

LangGraph's checkpointer turns this into a structured workflow. State after every node execution is snapshotted with a unique id. You can list snapshots, edit state at any one of them, and replay forward from the corrected state. And the original timeline stays intact for comparison.

The three APIs and the pinned checkpoint id discipline are the entire story. The question is whether you can walk a real run through it.

The checkpointer. What gets written

A checkpointer implements a small interface: write a snapshot of state for (thread_id, checkpoint_id) after every node, optionally pointing to a parent_checkpoint_id. LangGraph ships three implementations:

An in-memory saver. In-process dictionary; great for tests, lost on restart.
A SQLite saver. Local file; great for local repro and demos.
A Postgres saver. Production; durable, multi-replica safe, JSONB column for state.

Every snapshot is a state snapshot carrying config (with thread_id, checkpoint_id, parent_checkpoint_id), values (the full state), next (which nodes will run if you resume here), tasks (pending node executions), and metadata (source, step number).

Step 1. Enumerate history

Step 2. Localise the bad decision

Step 3. Fork by pinning the checkpoint_id

Step 4 and 5. Replay and diff

Why AgentExecutor cannot do this

Situations where this technique stops working.

2–4 min · Everything important, quickly.

python

from langgraph.checkpoint.postgres import PostgresSaver

checkpointer = PostgresSaver.from_conn_string(POSTGRES_URL)
app = graph.compile(checkpointer=checkpointer)

cfg = {"configurable": {"thread_id": "t-42"}}

# 1) List history
history = list(app.get_state_history(cfg))
for snap in history:
    print(snap.config["configurable"]["checkpoint_id"], snap.next, snap.values)

# 2) Pick the bad checkpoint, fork by pinning checkpoint_id
bad_id = history[3].config["configurable"]["checkpoint_id"]
new_cfg = app.update_state(
    config={"configurable": {"thread_id": "t-42", "checkpoint_id": bad_id}},
    values={"messages": history[3].values["messages"] + [corrected_msg]},
)

# 3) Replay forward from the corrected state
result = app.invoke(None, config=new_cfg)

Real products, models, and research that use this idea.

LangGraph's official `human-in-the-loop` tutorial uses the same primitives, list state, edit at a point, resume, for human approval gates
Production support workflows at several YC AI startups use Postgres checkpointer plus LangSmith to triage bad agent runs by forking from the bad node

What an interviewer would ask next. Try answering before peeking at the approach.

QHow does the Postgres checkpointer schema represent the parent-child relationship between checkpoints?

Walk through the checkpoint table with thread_id, checkpoint_id, parent_checkpoint_id columns and how branches form a DAG rooted at the initial state.

2 more follow-ups an interviewer would ask next. Sign in to reveal them.

Red flags & common mistakes

The phrases that signal junior thinking. Click to expand.

Most common mistake

Calling `update_state` without pinning a `checkpoint_id`. That mutates the latest state instead of forking, and you lose the ability to compare the original run against your corrected branch.

60 second bullets to scan on the way to the call.

Three APIs of the time-travel workflow
Why pinning checkpoint_id forks instead of mutating

Primary sources. Browse if you want the original framing.