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.
Quick reference
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.
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.
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example.
Stateless single-call workloads with no agent loop Checkpoints have nothing useful to record; time-travel solves a problem the workload does not have.
Strict-latency surfaces where Postgres writes per node are too slow Per-node checkpointing has IO cost; for latency-critical loops use MemorySaver in production only if loss of durability is acceptable.
Workloads where state contains data that must not be persisted (PII, secrets) Checkpointers write state to disk; routing secrets through state writes them to the checkpoint store and creates a compliance problem.
Single-turn tool calls where standard logging covers debugging Time-travel is overkill for workloads where one prompt and one response are the whole interaction.
Quick scan · 2–4 min
Everything important, quickly.
8 min: three APIs, pinned checkpoint_id fork semantics, re-invocation contract, checkpointer choices, parent_config DAG, why AgentExecutor cannot do this.
Code example
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-world examples
Real products, models, and research that use this idea.
1LangGraph's official `human-in-the-loop` tutorial uses the same primitives, list state, edit at a point, resume, for human approval gates
2Production support workflows at several YC AI startups use Postgres checkpointer plus LangSmith to triage bad agent runs by forking from the bad node
3Anthropic's research-agent reference implementation exercises time-travel as the canonical debugging story for multi-step planning runs
Interviewer follow-ups
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?
Sign in or go Pro to see the approach for this follow-up.
QWhat happens if you update_state at a checkpoint that has multiple downstream branches already?
Sign in or go Pro to see the approach for this follow-up.
QHow does human in the loop interrupt interact with time-travel?
Sign in or go Pro to see the approach for this follow-up.
Don't say this
Red flags and common mistakes 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.