Execution Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Execution Engine is the core component of the n8n platform responsible for processing workflows. It handles the traversal of the workflow graph, manages the lifecycle of node executions, and orchestrates the flow of data between connected nodes. The engine operates on a node-based architecture where workflows are defined as a graph of nodes, starting from one or more trigger nodes that initiate the execution process.
Sources: AGENTS.md:124-126, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:33-36
Execution Model and Item Cardinality
The n8n execution model is fundamentally item-based. Every node in a workflow executes once for each input item it receives. This behavior governs how data is processed across the entire graph.
The "Per-Item" Rule
When a trigger or a previous node outputs multiple items (e.g., a Gmail node returning 10 emails), every downstream node will run once for each of those 10 items. This can lead to item multiplication if multiple independent sources are chained together without specific flow control.
Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:47-50
Controlling Execution Density
To manage item multiplication or ensure a node only runs once regardless of input volume, the engine provides specific configuration flags:
| Setting | Description | Use Case |
|---|---|---|
executeOnce | Forces a node to run exactly once for all incoming items. | Summary notifications, report generation, or shared-context fetches. |
alwaysOutputData | Forces a branch to continue even if the predecessor emitted zero items. | Mandatory outcomes like digests or alerts that must send empty states. |
Sources: packages/@n8n/instance-ai/skills/workflow-builder/SKILL.md:529-535, packages/@n8n/instance-ai/skills/workflow-builder/SKILL.md:550-555
Visualizing Item Flow
The following diagram illustrates how item cardinality shifts as it passes through different node types:
This diagram shows the expansion and contraction of items through the workflow. Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:49-51, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:114-118
Workflow Topologies
The engine supports several architectural patterns for connecting nodes, ranging from simple linear chains to complex multi-agent systems.
Linear and Parallel Execution
Workflows can be structured as simple sequences or can branch out into parallel processing paths. Parallel branches execute independently, and their results can be synchronized using Merge nodes.
Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:62-100, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:182-200
Fan-in and Fan-out
- Fan-out: Occurs when a single node connects to multiple downstream nodes, or when a node outputs multiple items.
- Fan-in: Occurs when multiple branches converge into a single node. Converging nodes must handle data from multiple potential paths, often requiring optional chaining in expressions (e.g.,
{{ $json.data?.approved ?? $json.status }}).
Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:251-270, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:405-410
Control Flow Primitives
The Execution Engine relies on specific "primitive" nodes to manage the logic of workflow traversal:
- IF Node: Provides binary (true/false) branching. Each branch defines a complete processing path.
- Switch Node: Routes items to multiple outputs based on rules or expressions. It uses zero-based indexing for its output cases.
- Merge Node: Combines data from multiple branches. It supports various modes such as
append,combine(by position or key), andwait. - Split In Batches: Facilitates looping by processing large datasets in chunks, looping back via a
nextBatchconnection until finished.
Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:153-230, packages/@n8n/instance-ai/skills/workflow-builder/SKILL.md:537-549
Branching Logic Flow
This diagram demonstrates the standard fan-out and fan-in logic used for conditional processing. Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:165-170, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:182-185
Expression Language and Data Access
The engine evaluates expressions at runtime to allow dynamic parameter configuration. These expressions have access to a rich context of variables.
Common Variables
$json: Refers to the current item's data from the immediate predecessor node.$('NodeName').item.json: Accesses output from a specific named node in the workflow, paired with the current item.$now/$today: Provides Luxon-powered date and time helpers.$execution.id/$runIndex: Metadata about the current execution instance.
Sources: packages/@n8n/instance-ai/skills/workflow-builder/SKILL.md:592-604
Data Scope Rules
When a node receives data from multiple branches (after a Switch or IF), referencing $json is only safe if that predecessor always runs. In complex topologies, it is safer to reference source nodes explicitly using nodeJson(sourceNode, 'field.path').
Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:412-415, packages/@n8n/instance-ai/skills/workflow-builder/SKILL.md:610-612
Execution Tracing and Status
The engine maintains a detailed trace of the workflow execution, which is used for debugging and reporting.
Node Execution Modes
During an execution, nodes can exist in several states as captured in execution reports:
- Real: The node was executed normally.
- Mocked: The node execution was simulated with mock data (often used in AI-assisted building).
- Pinned: The node used user-supplied static data instead of executing its logic.
- Disabled: The node was skipped during traversal.
Sources: packages/@n8n/instance-ai/evaluations/report/workflow-report.ts:142-151, packages/@n8n/instance-ai/evaluations/report/workflow-report.ts:620-630
Execution Life Cycle
The following sequence diagram outlines how the engine initiates and tracks a node execution:
This diagram represents the internal logic for resolving data before and after a node's primary logic runs. Sources: packages/@n8n/instance-ai/evaluations/report/workflow-report.ts:630-650, packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:47-50
Conclusion
The Execution Engine provides a robust, item-centric framework for automating complex business logic. By combining a "run-once-per-item" model with sophisticated control flow primitives and a dynamic expression language, it allows for highly flexible workflow designs that can scale from simple linear tasks to complex, multi-branched parallel processes.