To debug a LangGraph run, compile the graph with a checkpointer, use the same thread_id for the run and inspection calls, then examine its latest snapshot and history. For a live run, stream node updates and task events. Once you identify the checkpoint before the faulty transition, replay or branch from it carefully: later nodes run again, so external calls and side effects may repeat.
Make the run inspectable first
State inspection depends on a checkpointer and thread identity. The checkpointer stores checkpoints, while thread_id tells LangGraph which thread’s state to retrieve or resume. This Python example uses an in-memory saver for a local experiment:
As an Amazon Associate I earn from qualifying purchases.
from langgraph.checkpoint.memory import InMemorySaver
checkpointer = InMemorySaver()
graph = builder.compile(checkpointer=checkpointer)
config = {"configurable": {"thread_id": "debug-run-123"}}
result = graph.invoke(inputs, config)Use that same config with state inspection and subsequent calls. In-memory state does not survive process loss; use a persistence backend appropriate to the deployment when state must outlive the process. In Agent Server deployments, the server manages persistence infrastructure. See the LangGraph persistence documentation for checkpointers, threads, and checkpoints.
Inspect the latest snapshot
graph.get_state(config) returns a StateSnapshot. Its fields help answer what the graph contains now and what it is scheduled to do next:
#1 Best Overall
snapshot = graph.get_state(config)
print(snapshot.values) # channel values at this checkpoint
print(snapshot.next) # node or nodes scheduled next; empty means complete
print(snapshot.metadata) # source, writes, and step metadata
print(snapshot.tasks) # task details, including errors or interrupts where presentAn empty next means execution is complete at that checkpoint; a populated value identifies the scheduled continuation. A snapshot is a symptom, not the full diagnosis: use history or stream events to determine how the state reached that point. To inspect a particular historical checkpoint, add its checkpoint ID to the configurable run configuration.
Walk backward to find the first bad transition
graph.get_state_history(config) yields snapshots in reverse chronological order, newest first. Compare adjacent snapshots and locate the earliest transition where a field becomes missing, malformed, or unexpectedly changed:
history = list(graph.get_state_history(config))
for snapshot in history:
print(snapshot.created_at, snapshot.metadata, snapshot.next, snapshot.values)Check metadata.writes to associate channel updates with the node that produced them, and next to see the scheduled continuation. Snapshots also carry checkpoint and parent checkpoint IDs, which help identify a starting point for replay. The official persistence guide documents state snapshots and history.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Watch a run while it executes
For a live diagnosis, stream the event types that match the question. This example requests node updates and task events:
for chunk in graph.stream(
inputs,
config=config,
stream_mode=["updates", "tasks"],
version="v2",
):
print(chunk)| Mode | What it helps you see | Requirement or use |
|---|---|---|
updates |
State updates emitted by each node. | Useful for locating the node that changed a channel. |
tasks |
Node task start and finish information, results, and errors. | Requires a checkpointer; useful for finding where execution failed. |
checkpoints |
Checkpoint events as snapshots are saved. | Requires a checkpointer; useful for tracking saved state. |
debug |
Node names, full state, and additional runtime metadata. | Includes checkpoint and task events; useful when you need a broad execution view. |
messages |
Streamed language-model tokens with node metadata. | Useful when the issue is in model output. |
To include nested graph output and namespaces, pass subgraphs=True. The official streaming guide currently recommends event streaming for new applications while retaining stream modes for direct runtime events and selected output. Check that guide when adopting a newer API version. It describes debug as a way to stream as much execution information as possible.
Check whether the state update behaved as designed
If a field seems overwritten, missing, or duplicated, inspect the state schema and its reducer before attributing the behavior to the model. A channel without a reducer is replaced by the new update. A reducer defines how an incoming value is combined with the prior value, so the same node output can produce different state depending on the channel’s declared behavior.
Rank #3
For message lists, add_messages appends new messages and updates an existing message when its ID matches. That means a message with an existing ID is not necessarily duplicated; it can replace or update that message. See the LangGraph Graph API documentation for state schemas and reducers.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Replay or branch from the checkpoint that isolates the fault
Replay from a historical checkpoint to skip earlier work and execute subsequent nodes again. This can hold prior results fixed while reproducing a later problem, but it is not a read-only inspection: model calls, API requests, interrupts, and other later operations can run again. Verify side-effecting nodes before replaying production work.
For an experiment with altered state, use update_state. It creates a new checkpoint rather than editing the old one, preserving the previous checkpoint and allowing a branch. Consult the persistence guide for replay and state updates.
Account for durability and interrupted nodes
LangGraph provides three durability modes. The choice affects when checkpoint writes are persisted relative to execution, so it matters when diagnosing a missing intermediate checkpoint after a process failure:
exit: persists when execution exits; intermediate state is not preserved for recovery from a mid-run process crash.async: persists while the next step executes; a process crash can occur before a checkpoint write completes.sync: writes a checkpoint before the next step begins, trading some performance for higher durability.
If a node is interrupted mid-execution, resumption restarts that node from its beginning. Successful task writes from other nodes in the same super-step can be reused. For an inconsistent resume, verify the thread ID and inspect the last completed checkpoint before changing the workflow.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Use node boundaries to narrow the search
When one node performs several operations, its output may not reveal which operation caused the fault. LangChain recommends splitting work when doing so improves intermediate visibility, isolates external services, or enables different retry strategies. For example, separating retrieval from model drafting makes it easier to distinguish poor search results from a generation problem. Smaller nodes expose more checkpoints and can limit repeated work on restart; excessive splitting adds complexity and is not automatically better. See the workflow design guidance.
Choose a recovery path based on the failure
- Transient network or rate-limit error: apply a retry policy to the node that calls the external service.
- Recoverable tool or parse error: store the error in graph state and route to a node that can adjust or repair the action.
- Missing user information: use an interrupt when the workflow is designed to pause for human input.
- Unexpected exception: let it surface during diagnosis rather than swallowing an error whose recovery behavior is unknown.
- Retries exhausted: route to a recovery or compensation path if the application needs one.
These patterns are covered in the LangGraph workflow design guidance.
Debug visually with LangSmith Studio
LangSmith Studio is an optional visual route for graphs available through the Agent Server protocol. In Graph mode, it can show traversed nodes and intermediate states, with time-travel debugging for inspecting state across execution. Chat mode is a simpler chat-testing interface and is supported only when graph state includes or extends MessagesState. Use Studio when a visual timeline helps reveal the faulty transition; use the direct APIs for local execution or automated diagnostics. See the Studio documentation.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Free tools Windows power users keep installed
One-click scans. No signup required.
