Production debugging is different from tutorial debugging because the system is now entangled with users, external tools, partial failures, persistence, and business consequences. You cannot just rerun everything casually and hope to learn from the result.
LangGraph helps because it gives you named steps, persistent state, and route boundaries. But those advantages only pay off when you build an incident response habit around them.
This page is the operations playbook: how to investigate live issues, isolate the bad boundary, and harden the graph so the same class of failure becomes rarer over time.
Not every bad output is the same. A slow run, a wrong route, a repeated tool call, a missing checkpoint, and an unauthorized action are different incident classes with different response playbooks.
Teams move faster when they classify incident types up front instead of treating all graph failures as “the agent was weird.”
Start with thread identity and status. Then inspect the latest state snapshot. Then replay node order, route decisions, tool results, and retries. Finally compare the run with a healthy baseline. This layered approach prevents premature theories.
A good investigator tries to find the first wrong step, not merely the most visible bad symptom.
Graph applications have recurring failure shapes: state overwritten by a later node, loop counters not incrementing, fallback routes never reaching END, interrupt resumes with malformed payloads, and tool nodes operating on stale state.
The faster you learn these patterns, the faster you can triage without reading every line of the system from scratch.
After a live issue, the question is not just “what broke?” It is “what guardrail would have made this cheaper to detect, cheaper to recover, or impossible to repeat?”
Those guardrails may be tests, route assertions, step limits, better eventing, stricter tool validation, or a dedicated review gate.
The best postmortems leave you with a refined graph design, not just a resolved ticket. Ask what state signal should have existed earlier, which edge should have been impossible, and where the incident should have surfaced automatically.
Graph systems become reliable not by never failing, but by becoming easier to reason about after each failure class appears.
Production debugging starts by naming the symptom precisely. Did the graph fail to start, route incorrectly, call the wrong tool, retry too often, resume from the wrong state, lose an interrupt, return a bad answer, or exceed budget? Each symptom points to a different layer.
Then inspect the run in graph order: input, initial state, selected route, node outputs, reducer merges, tool results, checkpoints, interrupts, retries, and final status. Skipping directly to the final answer hides the mechanics that caused it.
State snapshots are especially important. Compare the state before and after the suspicious node. If the wrong field changed, the bug may be in node output. If two updates merged incorrectly, the reducer may be wrong. If route input is correct but route output is wrong, test the router with a tiny fixture.
Production debugging should produce an artifact: incident summary, root cause, affected graph version, trace link, failed expectation, and regression test. Without that loop, teams solve the same class of graph bug repeatedly.
Interrupted runs create special debugging questions. Was the interrupt created at the right point? Was the pending state persisted? Did the resume command include the expected data? Did the graph re-run a side effect when it resumed? These questions require checkpoint and trace visibility.
Side effects should be isolated around resume boundaries. If a node sends an external message and then interrupts, replay or resume can become dangerous. Prefer drafting before interrupt and executing after approval, or use idempotency keys and durable records to prevent duplicate actions.
When a resumed run behaves differently, compare the checkpointed state with the current graph code. Deployment changes may alter route logic, state interpretation, or tool behavior. This is why graph versioning and state schema versioning matter in production debugging.
Operators also need safe repair paths. Sometimes the right answer is to cancel a stuck run, resume with corrected input, or migrate a checkpoint. These actions should be audited because they affect workflow history.
Run a debugging drill with one intentionally broken graph. Make the router choose the wrong branch, make a reducer overwrite state, or make a tool timeout. Then ask a developer to find the first wrong transition using traces and state snapshots.
The drill should produce a short incident report: symptom, first bad state, root cause, affected version, user impact, fix, and regression test. This practice builds the muscle needed for real incidents.
Also test operator actions. Can someone cancel a stuck run, inspect an interrupted run, identify pending approvals, and replay safely without repeating side effects? Debuggability includes the tools humans use under pressure.
Repeat the drill after major graph changes so the team knows whether new nodes, routes, and persistence behavior remain explainable under pressure.
Persist graph, state-schema, prompt, model, tool, and serializer versions with each release and trace. LangGraph applies the latest graph definition when a thread resumes rather than pinning a thread automatically to its starting code. Removing or renaming the node where execution paused can leave no valid resume point.
Classify changes as compatible, migratable, or requiring old workers. Additive state fields with defaults are usually easier than changed reducer meaning or removed channels. Maintain checkpoint migration tests and route long-paused threads to compatible code when a direct resume is unsafe.
During incidents, freeze writes or high-risk tools first, then compare error rate and state transitions by release. Preserve checkpoint and trace evidence, reproduce from a sanitized snapshot, and verify rollback against both new and old state. A code rollback that cannot deserialize recent checkpoints is not a recovery plan.
Even a simple structured record beats vague notes when debugging production runs.
incident = {
"thread_id": "support-301",
"status": "failed",
"first_bad_node": "draft_reply",
"symptom": "reply ignored refund policy",
"last_route": "billing_path",
}A compact tool audit log can reveal repeated or invalid calls quickly.
tool_audit = [
{"tool": "search_docs", "status": "ok", "duration_ms": 320},
{"tool": "lookup_order", "status": "error", "duration_ms": 180},
{"tool": "lookup_order", "status": "ok", "duration_ms": 175},
]During incident triage, route comparisons can pinpoint the earliest business-logic divergence.
route_check = {
"node": "route_after_evaluate",
"expected": "human_review",
"actual": "publish",
"quality_score": 0.42,
"risk": "high",
}Thread identity, current status, and the earliest suspicious state transition you can find.
Look for where the run first diverged: route, state, tool result, retry path, or model output. The trace usually reveals the boundary.
Capture enough structured evidence per run that you can explain the workflow without rerunning it blindly.
Explore 500+ free tutorials across 20+ languages and frameworks.