Principle:Langchain ai Langgraph Debug Event Emission
| Attribute | Value |
|---|---|
| Knowledge Sources | LangGraph |
| Domains | Debugging, Execution |
| Last Updated | 2026-02-11 15:00 GMT |
Overview
Debug event emission is the mechanism by which LangGraph's Pregel execution engine produces structured diagnostic payloads -- including task starts, task results, and checkpoint snapshots -- when a graph is streamed with stream_mode="debug".
Description
When developers need visibility into the internal execution of a LangGraph graph, they can activate the debug streaming mode. This mode hooks into three key lifecycle points of the Pregel execution engine and emits structured events that expose what is happening inside the graph at each superstep.
The three event types are:
- Task events -- Emitted at the start of each superstep via
map_debug_tasks. Each payload provides the task ID, target node name, input value, and the trigger channels that caused the task to execute. Tasks tagged withTAG_HIDDENare excluded from debug output to avoid cluttering the stream with internal bookkeeping.
- Task result events -- Emitted after a task completes via
map_debug_task_results. Each payload includes the task ID, node name, any error string, the channel writes aggregated into a result dictionary, and a list of serialized interrupt objects. When multiple writes target the same channel, they are wrapped in a{"$writes": [...]}envelope by themap_task_result_writeshelper.
- Checkpoint events -- Emitted at the end of each superstep via
map_debug_checkpoint. These provide a comprehensive snapshot including the current config, parent config, channel values, metadata, the list of next nodes to execute, and enriched task details. Thetasks_w_writeshelper joins tasks with their pending writes from the checkpointer to construct completePregelTasktuples with error, interrupt, result, and subgraph state information.
All events are formalized as TypedDict classes (TaskPayload, TaskResultPayload, CheckpointTask, CheckpointPayload) that define the exact shape of each event, making it straightforward to build typed consumers of the debug stream. The module also provides terminal coloring utilities (get_colored_text, get_bolded_text) for console-based debug output in development environments.
Usage
Activate debug event emission by streaming a compiled graph with stream_mode="debug". This is valuable during development for understanding execution flow, diagnosing unexpected routing, inspecting intermediate state, and verifying that the correct nodes are triggered by the expected channels. The debug stream can also be used in production monitoring pipelines to capture detailed execution traces.
Application developers consume the resulting events through the stream iterator but do not call the underlying functions directly. The TypedDict definitions are useful for understanding and typing debug event consumers, for example when building custom dashboards or logging integrations.
Theoretical Basis
Debug event emission follows the observer pattern, where the execution engine acts as the subject and the stream consumer acts as the observer. The engine does not alter its behavior based on whether debug mode is active; it simply emits additional structured events at predefined lifecycle points when the mode is enabled.
The three-event taxonomy (task start, task result, checkpoint) mirrors the natural phases of a Pregel superstep: scheduling, execution, and persistence. This gives consumers a complete picture of each superstep without requiring them to reconstruct state from lower-level primitives. The task/task-result pairing is analogous to span-based tracing in distributed systems, where each unit of work has a begin and end marker with associated metadata.
The use of TypedDict definitions for event payloads provides a formal schema that enables static type checking of debug stream consumers, ensuring that tools built on top of the debug stream remain correct as the event format evolves. This is a form of contract-first design where the event schema is defined independently of the event producer.