Execution Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Execution Engine manages the lifecycle of workflow runs within n8n. It coordinates the progression of execution states, handles node-level processing, and persists run data through specialized storage interfaces. The architecture follows a modular "Engine v2" design that separates pure orchestration logic from effectful implementations like database persistence and message queuing.
Sources: packages/@n8n/engine/AGENTS.md, packages/engine/src/runtime/create-engine-runtime.ts:1-20
Architecture Layers
The engine employs a "ports and adapters" pattern to maintain clean boundaries between core logic and infrastructure.
- Core Layer: Decides orchestration policy. It contains pure logic for graphs and executions. It does not open network connections or read environment variables directly.
- Core Interfaces: Defines the contracts that the Core Layer depends on, such as
ExecutionStoreandWorkQueue. - Adapters: Implements the core interfaces using specific technologies like TypeORM for Postgres or in-memory queues.
- Runtime Factory: Aggregates these components into a running engine instance.
Sources: packages/@n8n/engine/AGENTS.md
Component Relationship Diagram
This diagram illustrates how the runtime factory assembles various services to create a functional execution environment.
Execution Lifecycle and State
The engine advances an execution through specific writes: claiming the execution, inserting step rows, and publishing messages. This sequence is not atomic; instead, a reconciliation layer identifies and recovers stalled runs.
Execution Record Structure
The ExecutionRecord tracks the high-level status and metadata of a workflow run.
| Field | Type | Description |
|---|---|---|
id | ExecutionId | Unique identifier for the run. |
workflowId | WorkflowId | The ID of the workflow being executed. |
status | ExecutionStatus | Current state (e.g., pending, running, success, failed). |
workflowGraph | WorkflowGraph | The structured representation of the workflow nodes and connections. |
variables | ExecutionVariables | Global variables associated with the specific run. |
Sources: packages/engine/src/execution/execution-store.ts:6-25
State Transitions
The engine manages transitions via the ExecutionStore interface methods.
Step Execution Logic
A step represents the execution of a single node within the workflow graph. The engine tracks individual steps to provide granular visibility into the run.
Step Data Model
| Component | Purpose |
|---|---|
StepRecord | Tracks specific node execution details including status and slot information. |
StepSummary | Provides a lightweight view of a step for reporting. |
StepSlots | Maps node input/output slots to specific data indices. |
Sources: packages/engine/src/execution/execution-store.ts:27-38
Iteration and Cardinality
The execution model follows a specific item-based logic:
- Every node executes once per input item.
- If a trigger or node outputs multiple items, every downstream node runs once for each item.
- Flow control nodes (e.g., Aggregate, Split Out) modify item cardinality by combining or expanding the item stream.
Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts
Runtime Configuration
The createEngineRuntime function serves as the composition root. It accepts a "dependencies bag" and returns a configured engine instance.
Runtime Dependencies
| Dependency | Interface | Role |
|---|---|---|
admittance | AdmittanceService | Determines if a workflow execution request is accepted. |
queue | WorkQueue | Manages the distribution of execution tasks to workers. |
store | ExecutionStore | Persists execution state and step history. |
executor | StepExecutor | Executes the actual logic of a workflow node (v1 compatibility layer). |
publisher | LifecycleEventPublisher | Emits events when execution states change. |
Sources: packages/engine/src/runtime/create-engine-runtime.ts:18-32
Error Handling and Recovery
The engine uses a reconciliation-based recovery strategy rather than distributed transactions.
- Partial State Handling: If a crash occurs between claiming an execution and publishing a message, the system identifies the mismatch.
- Reconciliation Layer: A background process detects executions stuck in the
runningstate with no active worker or queued steps and re-queues them. - Dependency Purity: To ensure reliability, the core engine packages avoid dependencies on
n8n-workflow(v1) to prevent leaking old execution concepts into the v2 architecture.
Sources: packages/@n8n/engine/AGENTS.md, packages/engine/src/execution/execution-store.ts:50-55
Execution Request Flow
The following sequence outlines how the engine handles a new execution request from start to completion.