Workflow Execution Engine

Relevant source files

• packages/@n8n/decorators/src/__tests__/memoized.test.ts
• packages/@n8n/decorators/src/context-establishment/context-establishment-hook.ts
• packages/@n8n/decorators/src/memoized.ts
• packages/@n8n/node-cli/src/commands/new/index.test.ts
• packages/cli/src/__tests__/active-executions.test.ts
• packages/cli/src/__tests__/workflow-execute-additional-data.test.ts
• packages/cli/src/__tests__/workflow-runner.test.ts
• packages/cli/src/active-executions.ts
• packages/cli/src/eventbus/event-message-classes/event-message-ai-node.ts
• packages/cli/src/eventbus/event-message-classes/event-message-audit.ts
• packages/cli/src/eventbus/event-message-classes/index.ts
• packages/cli/src/eventbus/message-event-bus/message-event-bus.ts
• packages/cli/src/events/__tests__/log-streaming-event-relay.test.ts
• packages/cli/src/events/__tests__/telemetry-event-relay.test.ts
• packages/cli/src/events/event.service.ts
• packages/cli/src/events/maps/relay.event-map.ts
• packages/cli/src/events/relays/log-streaming.event-relay.ts
• packages/cli/src/events/relays/telemetry.event-relay.ts
• packages/cli/src/execution-lifecycle/__tests__/execution-lifecycle-hooks.test.ts
• packages/cli/src/execution-lifecycle/execution-lifecycle-hooks.ts
• packages/cli/src/execution-lifecycle/shared/shared-hook-functions.ts
• packages/cli/src/executions/execution-recovery.service.ts
• packages/cli/src/interfaces.ts
• packages/cli/src/scaling/__tests__/job-processor.service.test.ts
• packages/cli/src/scaling/__tests__/scaling.service.test.ts
• packages/cli/src/scaling/job-processor.ts
• packages/cli/src/scaling/scaling.service.ts
• packages/cli/src/scaling/scaling.types.ts
• packages/cli/src/webhooks/__tests__/webhook-helpers.test.ts
• packages/cli/src/webhooks/webhook-helpers.ts
• packages/cli/src/workflow-execute-additional-data.ts
• packages/cli/src/workflow-runner.ts
• packages/core/eslint.config.mjs
• packages/core/src/execution-engine/__tests__/mock-node-types.ts
• packages/core/src/execution-engine/__tests__/requests-response.test.ts
• packages/core/src/execution-engine/__tests__/workflow-execute-process-process-run-execution-data.test.ts
• packages/core/src/execution-engine/__tests__/workflow-execute-run-node.test.ts
• packages/core/src/execution-engine/__tests__/workflow-execute.test.ts
• packages/core/src/execution-engine/node-execution-context/credentials-test-context.ts
• packages/core/src/execution-engine/node-execution-context/execute-single-context.ts
• packages/core/src/execution-engine/node-execution-context/index.ts
• packages/core/src/execution-engine/node-execution-context/utils/__tests__/resolve-source-overwrite.test.ts
• packages/core/src/execution-engine/node-execution-context/utils/resolve-source-overwrite.ts
• packages/core/src/execution-engine/requests-response.ts
• packages/core/src/execution-engine/workflow-execute.ts
• packages/core/src/node-execute-functions.ts
• packages/core/src/utils/__tests__/deep-merge.test.ts
• packages/core/src/utils/deep-merge.ts

Purpose and Scope

This document describes the core workflow execution engine in n8n, which is responsible for orchestrating the execution of workflow nodes, managing data flow between nodes, and handling the execution lifecycle. The engine implements a stack-based execution model that processes nodes sequentially while maintaining execution state.

For detailed information about specific aspects of execution:

• Workflow execution lifecycle and node contexts: See Workflow Execution Lifecycle
• Distributed execution with workers and queues: See Distributed Execution and Scaling
• Expression resolution and data access patterns: See Workflow Data Access and Expression System
• Partial execution, pin data, and error handling: See Partial Execution and Error Handling

---

Architecture Overview

The workflow execution engine orchestrates workflow execution through multiple layers, from entry point to completion. The WorkflowRunner service is the main entry point, which decides between regular in-process execution and distributed queue-based execution. Once execution begins, the WorkflowExecute class coordinates node scheduling, data routing, and lifecycle management.

High-Level Architecture

The diagram below maps the key code classes to their roles in the execution pipeline.

Workflow Execution Engine — Class and Data Flow

Sources: packages/cli/src/workflow-runner.ts51-213 packages/cli/src/scaling/scaling.service.ts39-110 packages/core/src/execution-engine/workflow-execute.ts86-187 packages/cli/src/active-executions.ts35-53

Execution Modes

n8n supports two execution modes configured via executions.mode:

Mode	Description	Use Case
regular	In-process execution in the main process	Single-server deployments, development
queue	Distributed execution via Bull queue and Redis	Multi-worker scaling, high availability

In regular mode, WorkflowRunner.runMainProcess() directly instantiates WorkflowExecute and runs the workflow in the current process.

In queue mode, WorkflowRunner.enqueueExecution() adds a job to the Bull queue. Worker processes pick up jobs via JobProcessor.processJob(), which then instantiates WorkflowExecute on the worker.

Sources: packages/cli/src/workflow-runner.ts139-188 packages/cli/src/workflow-runner.ts378-545 packages/cli/src/scaling/job-processor.ts71-140

---

Core Components

WorkflowRunner

The WorkflowRunner class is the primary entry point for workflow execution. It handles execution mode selection, credential checks, and error recovery.

Key Responsibilities:

• Register new executions via ActiveExecutions.add()
• Validate credential permissions via CredentialsPermissionChecker
• Choose between regular and queue mode execution
• Handle execution errors via processError()
• Manage execution timeouts

Key Methods:

Sources: packages/cli/src/workflow-runner.ts51-69 packages/cli/src/workflow-runner.ts139-213 packages/cli/src/workflow-runner.ts217-376 packages/cli/src/workflow-runner.ts72-134

ActiveExecutions

The ActiveExecutions service tracks all currently running executions in the process. It manages execution state, response promises, and provides cancellation capabilities.

Key Responsibilities:

• Track active executions with add() and finalizeExecution()
• Store response promises for webhook-triggered executions
• Attach workflow execution promises for cancellation
• Handle streaming chunks for real-time updates
• Manage concurrency control reservations

Key Methods:

Sources: packages/cli/src/active-executions.ts35-53 packages/cli/src/active-executions.ts62-145 packages/cli/src/active-executions.ts244-290

WorkflowExecute Class

The WorkflowExecute class is the main orchestrator for workflow execution. It maintains the execution state and processes nodes from the execution stack.

Key Responsibilities:

• Initialize and manage the node execution stack (nodeExecutionStack)
• Process nodes sequentially using processRunExecutionData()
• Route data between nodes via addNodeToBeExecuted()
• Handle waiting nodes with incomplete input data
• Support two execution orders: v0 (legacy) and v1

Class Structure:

Sources: packages/core/src/execution-engine/workflow-execute.ts86-96 packages/core/src/execution-engine/workflow-execute.ts98-165

ScalingService (Queue Mode)

The ScalingService manages the Bull queue for distributed execution. It runs on main/webhook processes for job submission and on worker processes for job consumption.

Key Responsibilities:

• Initialize Bull queue with Redis connection
• Add jobs to queue via addJob()
• Process job progress messages (webhooks, chunks, completion)
• Track running jobs and queue metrics
• Recover dangling executions from queue

Key Methods:

Sources: packages/cli/src/scaling/scaling.service.ts40-56 packages/cli/src/scaling/scaling.service.ts60-109 packages/cli/src/scaling/scaling.service.ts111-137 packages/cli/src/scaling/scaling.service.ts226-249

JobProcessor (Queue Mode)

The JobProcessor runs on worker processes to execute jobs from the queue. It fetches execution data from the database, instantiates WorkflowExecute, and reports results back.

Key Responsibilities:

• Fetch execution data from ExecutionRepository
• Create execution contexts with lifecycle hooks
• Instantiate and run WorkflowExecute
• Send webhook responses and streaming chunks via job progress
• Report job completion or failure

Key Methods:

Sources: packages/cli/src/scaling/job-processor.ts55-69 packages/cli/src/scaling/job-processor.ts71-220

Execution Contexts

Execution contexts provide the runtime environment for node execution. They implement different interfaces depending on the node type:

Context Class	Interface	Use Case
ExecuteContext	IExecuteFunctions	Standard nodes with execute() method
SupplyDataContext	ISupplyDataFunctions	AI nodes with supplyData() method
PollContext	IPollFunctions	Poll trigger nodes
WebhookContext	IWebhookFunctions	Webhook nodes

Common Context Features:

• Access to node parameters via getNodeParameter()
• Input data retrieval via getInputData()
• Helper functions for HTTP requests, binary data, credentials
• Workflow data proxy for expression resolution
• Execution cancellation signal handling

Sources: packages/core/src/execution-engine/node-execution-context/execute-context.ts48-134 packages/core/src/execution-engine/node-execution-context/supply-data-context.ts43-121

Node Execution Stack

The execution stack is an array of IExecuteData objects representing nodes to be executed. The engine processes this stack in order (FIFO for v1, LIFO for v0).

IExecuteData Structure:

Stack Operations:

• Push: nodeExecutionStack.push() or .unshift() (depending on execution order)
• Pop: Nodes are taken from the front via .shift()
• Waiting: Nodes with incomplete inputs go to waitingExecution map

Sources: packages/workflow/src/interfaces.ts439-446 packages/core/src/execution-engine/workflow-execute.ts394-795

Data Structures

IRunExecutionData

The main execution state container, defined in packages/workflow. It holds three top-level sections:

Field	Type	Purpose
resultData.runData	IRunData	Execution results keyed by node name
resultData.pinData	IPinData?	Manually pinned test data
resultData.error	ExecutionBaseError?	Terminal error if execution failed
executionData.nodeExecutionStack	IExecuteData[]	Nodes pending execution
executionData.waitingExecution	IWaitingForExecution	Nodes with partial input data
executionData.waitingExecutionSource	IWaitingForExecutionSource	Source tracking for waiting nodes
startData.destinationNode	IDestinationNode?	Target node for partial runs
startData.runNodeFilter	string[]?	Allowlist of nodes to execute
waitTill	Date?	Timestamp when a wait node should resume

See packages/workflow/src/interfaces.ts for the full interface definition.

ITaskData

Execution result for a single node invocation. Each entry in runData[nodeName] is an ITaskData[] (one per loop iteration or trigger emission).

Field	Type	Purpose
startTime	number	Unix ms when node started
executionTime	number	Duration in ms
executionStatus	ExecutionStatus?	success, error, skipped, etc.
data	ITaskDataConnections?	Output data per connection type
error	ExecutionBaseError?	Node error if execution failed
source	ISourceData[]	Which upstream node/output sent data
metadata	ITaskMetadata?	Sub-run relationships, tool call refs
hints	NodeExecutionHint[]?	User-visible hints from the node

Sources: packages/workflow/src/interfaces.ts1550-1700 packages/core/src/execution-engine/workflow-execute.ts296-340

---

Execution Flow

Complete Execution Flow

The complete execution flow from trigger to completion, showing both regular and queue mode paths.

End-to-End Execution — Regular vs Queue Mode

Sources: packages/cli/src/workflow-runner.ts139-213 packages/cli/src/workflow-runner.ts217-376 packages/cli/src/workflow-runner.ts378-545 packages/cli/src/scaling/job-processor.ts71-220 packages/cli/src/active-executions.ts244-290

WorkflowExecute Main Loop

Once WorkflowExecute is instantiated, the main execution loop in processRunExecutionData() processes nodes from the stack.

WorkflowExecute.processRunExecutionData() — Inner Loop

Sources: packages/core/src/execution-engine/workflow-execute.ts1282-2200 packages/core/src/execution-engine/requests-response.ts

Stack-Based Execution Model

The engine uses nodeExecutionStack: IExecuteData[] to track pending nodes. The executionOrder workflow setting controls the stack operation:

executionOrder setting	Stack operation	Effect
v1 (default)	push / shift (FIFO)	Breadth-first; siblings execute before children
v0 (legacy)	unshift / shift (LIFO)	Depth-first; children execute before siblings

The isLegacyExecutionOrder() method in WorkflowExecute checks workflow.settings.executionOrder !== 'v1' to decide which mode applies.

Example execution order (v1):

Initial stack:  [Trigger]
After Trigger:  [Node1, Node2]       push both children
After Node1:    [Node2, Node3]       push Node3 at end
After Node2:    [Node3, Node4]       push Node4 at end
After Node3:    [Node4]
After Node4:    []                   done

Nodes with multiple inputs go into waitingExecution until all upstream data arrives, then are promoted back to nodeExecutionStack by addNodeToBeExecuted().

Sources: packages/core/src/execution-engine/workflow-execute.ts1282-1400 packages/core/src/execution-engine/workflow-execute.ts189-191 packages/core/src/execution-engine/workflow-execute.ts406-417

---

Node Types and Execution

Standard Nodes (execute)

Most nodes implement the execute() method which is called via ExecuteContext:

Execution Path:

1. WorkflowExecute.runNode() creates ExecuteContext
2. Calls node.execute.call(executeContext)
3. Node accesses input via this.getInputData()
4. Returns INodeExecutionData[][] (array per output)
5. Results stored in runData[nodeName]

Sources: packages/core/src/execution-engine/workflow-execute.ts1100-1200 packages/core/src/execution-engine/node-execution-context/execute-context.ts48-246

AI Nodes (supplyData)

AI nodes (LangChain nodes) use supplyData() to provide objects (tools, models, etc.) rather than data:

Key Differences:

• Uses SupplyDataContext instead of ExecuteContext
• Returns object in response field, not data arrays
• Often used for nodes that are connected via AI connection types
• Can track multiple runs via getNextRunIndex()

Sources: packages/core/src/execution-engine/node-execution-context/supply-data-context.ts43-144 packages/core/src/execution-engine/node-execution-context/utils/get-input-connection-data.ts96-202

Trigger and Polling Nodes

Trigger nodes use different contexts and don't run in the normal execution loop:

• Trigger Nodes: Use ITriggerFunctions, emit data via emit()
• Poll Nodes: Use IPollFunctions, check for new data periodically
• Webhook Nodes: Use IWebhookFunctions, activated via HTTP requests

These are managed by ActiveWorkflowManager rather than WorkflowExecute. See the Node System section (page 4) for how node types are discovered and registered.

Sources: packages/workflow/src/interfaces.ts1183-1201 packages/core/src/execution-engine/triggers-and-pollers.ts </old_str> <new_str>

Trigger and Polling Nodes

Trigger nodes use different contexts and don't run in the normal execution loop:

• Trigger Nodes: Use ITriggerFunctions, emit data via emit()
• Poll Nodes: Use IPollFunctions, check for new data periodically
• Webhook Nodes: Use IWebhookFunctions, activated via HTTP requests

These are managed by ActiveWorkflowManager rather than WorkflowExecute. See the Node System section (page 4) for how node types are discovered and registered.

Sources: packages/workflow/src/interfaces.ts1183-1201 packages/core/src/execution-engine/triggers-and-pollers.ts

---

AI Agent Execution

EngineRequest and EngineResponse

AI Agent nodes can request tool execution by returning an EngineRequest instead of normal data. This allows agents to dynamically invoke workflow nodes as tools.

EngineRequest Structure

EngineResponse Structure

Sources: packages/workflow/src/interfaces.ts2800-2850 packages/core/src/execution-engine/requests-response.ts1-20

Tool Execution Flow

AI Agent Tool Loop — EngineRequest/EngineResponse Protocol

Sources: packages/core/src/execution-engine/workflow-execute.ts1900-2100 packages/core/src/execution-engine/requests-response.ts28-200

Request Handling Implementation

When WorkflowExecute.runNode() detects an EngineRequest:

1. Detection: isEngineRequest(result) checks if output is a request object
2. Preparation: prepareRequestedNodesForExecution() creates IExecuteData for each tool
3. Tool Execution: Tools are added to stack and executed normally
4. Response Building: makeEngineResponse() collects tool results into EngineResponse
5. Agent Resume: Agent node re-executes with subNodeExecutionResults in context

Key Code Paths:

• Request detection: packages/core/src/execution-engine/workflow-execute.ts1900-1950
• Tool scheduling: packages/core/src/execution-engine/requests-response.ts28-125
• Response creation: packages/core/src/execution-engine/requests-response.ts127-200

Sources: packages/core/src/execution-engine/workflow-execute.ts1900-2100 packages/core/src/execution-engine/requests-response.ts1-200

Tool Node Invocation

Tools can be regular workflow nodes that are invoked by AI agents. The WorkflowToolService wraps workflow execution as a LangChain tool:

The tool handler:

1. Calls context.executeWorkflow() to run the tool's workflow
2. Handles retries if retryOnFail is enabled
3. Returns stringified JSON response to the agent
4. Tracks execution via subExecutionId for linking

Sources: packages/@n8n/nodes-langchain/nodes/tools/ToolWorkflow/v2/utils/WorkflowToolService.ts43-220

---

Execution State Management

RunData Structure

All execution results are stored in runData, a map from node names to task data arrays:

Each ITaskData represents one execution of the node (nodes can run multiple times in loops).

Waiting Execution

When a node has multiple inputs and not all data has arrived, it goes into waitingExecution:

Wait Resolution:

1. incomingConnectionIsEmpty() checks if all inputs have data
2. If not all ready, prepareWaitingToExecution() creates waiting entry
3. addNodeToBeExecuted() adds data to waiting entry
4. When complete, node moves from waitingExecution to nodeExecutionStack

Sources: packages/core/src/execution-engine/workflow-execute.ts337-381 packages/core/src/execution-engine/workflow-execute.ts384-795

Metadata Tracking

Execution metadata is tracked separately and merged at the end:

This allows tracking:

• Sub-workflow executions
• Tool invocations
• Child node relationships

Sources: packages/core/src/execution-engine/workflow-execute.ts296-318

---

Error Handling

Execution Error Processing

The WorkflowRunner.processError() method handles execution errors and ensures proper cleanup:

Error Handling Logic:

1. Early Return: Skip processing for cancelled executions or ExecutionNotFoundError
2. Queue Mode Sanity Check: In queue mode, verify execution wasn't already marked successful (Bull stall edge case)
3. Create Error Run Data: Build IRun with error details
4. Finalize Execution: Remove from ActiveExecutions and mark as failed
5. Run Hooks: Execute workflowExecuteAfter hook for error workflows

Sources: packages/cli/src/workflow-runner.ts72-134

Node-Level Error Handling

Errors during node execution are captured and stored:

Error Types:

• NodeOperationError - Node-specific errors
• NodeApiError - API request errors
• ExecutionCancelledError - User cancelled
• TimeoutExecutionCancelledError - Timeout
• ManualExecutionCancelledError - Manual cancellation

Continue on Fail: If node.continueOnFail === true, execution continues with error stored in task data.

Sources: packages/core/src/execution-engine/workflow-execute.ts938-970 packages/workflow/src/interfaces.ts92-98

Execution Timeout

Timeouts are enforced in WorkflowRunner.runMainProcess():

The timeout:

• Uses workflow-specific setting or global default
• Capped at executions.maxTimeout configuration
• Adjusted if execution was previously waiting
• Calls ActiveExecutions.stopExecution() to cancel

Sources: packages/cli/src/workflow-runner.ts235-343

Cancellation Support

Execution can be cancelled via AbortController:

Nodes receive the abort signal via getExecutionCancelSignal() and can check:

• abortSignal.aborted - Is execution cancelled?
• Use signal with HTTP requests, sleep functions, etc.

The ActiveExecutions.stopExecution() method cancels running workflows:

Sources: packages/core/src/execution-engine/workflow-execute.ts89-90 packages/core/src/execution-engine/node-execution-context/base-execute-context.ts100-120 packages/cli/src/active-executions.ts244-290

Queue Mode Error Handling

In queue mode, worker errors are reported back to main via job progress messages:

The main process listens for these messages and logs them:

Sources: packages/cli/src/scaling/job-processor.ts139-161 packages/cli/src/scaling/scaling.service.ts398-411

---

Execution Modes

The engine supports multiple execution modes affecting behavior:

Mode	Description	Use Case
manual	User-triggered in UI	Testing, development
trigger	Activated by trigger	Production workflows
webhook	HTTP webhook trigger	API integrations
integrated	Called from another system	Embedded n8n
chat	Chat interface execution	AI chat workflows
internal	Internal system use	Queue workers

Mode Effects:

• Logging: manual mode sends data to UI via hooks
• Streaming: Enabled for manual, webhook, integrated, chat
• Error handling: manual shows detailed errors, trigger logs to database

Sources: packages/workflow/src/execution-context.ts1-50 packages/core/src/execution-engine/node-execution-context/execute-context.ts136-149

---

Execution Lifecycle Hooks

Lifecycle hooks allow external systems to observe and react to execution events. The ExecutionLifecycleHooks class extends the base LifecycleHooks from n8n-core with execution-specific functionality.

Hook Types

The ExecutionLifecycleHooks class supports the following hook types:

Hook Name	When Called	Parameters	Purpose
workflowExecuteBefore	Before workflow starts	[Workflow?, IRunExecutionData?]	Initialize workflow context
workflowExecuteAfter	After workflow completes	[IRun]	Save results, trigger events
nodeExecuteBefore	Before each node	[nodeName]	Track node start, log
nodeExecuteAfter	After each node	[nodeName]	Track node completion
sendChunk	Streaming chunk sent	[StructuredChunk]	Real-time streaming updates
sendResponse	Response sent	[IExecuteResponsePromiseData]	Webhook response handling

Sources: packages/cli/src/execution-lifecycle/execution-lifecycle-hooks.ts28-76

Hook Factory Functions

Different execution contexts require different hook configurations. All factory functions are defined in packages/cli/src/execution-lifecycle/execution-lifecycle-hooks.ts

Factory Function	Used By	Key Responsibilities
getLifecycleHooksForRegularMain()	WorkflowRunner.runMainProcess()	Save to DB, send UI push, telemetry, error workflows
getLifecycleHooksForScalingMain()	WorkflowRunner.enqueueExecution()	Minimal — only workflowExecuteBefore (worker does the rest)
getLifecycleHooksForScalingWorker()	JobProcessor.processJob()	Save to DB, report job result, MCP broadcast
getLifecycleHooksForSubExecutions()	executeWorkflow() in workflow-execute-additional-data.ts	Save with parent relationship, external hooks

Sources: packages/cli/src/execution-lifecycle/execution-lifecycle-hooks.ts78-287 packages/cli/src/workflow-runner.ts277-294

Hook Usage Example

Hooks are used for:

• Persisting execution results to database
• Sending real-time updates to UI (manual mode)
• Triggering telemetry and analytics events
• Running external integrations
• Executing error workflows on failure

Sources: packages/cli/src/workflow-runner.ts277-294 packages/cli/src/execution-lifecycle/execution-lifecycle-hooks.ts1-287

---

Key Classes and Files

Class/File	Purpose	Location
WorkflowExecute	Main execution orchestrator	packages/core/src/execution-engine/workflow-execute.ts
ExecuteContext	Runtime context for execute() nodes	packages/core/src/execution-engine/node-execution-context/execute-context.ts
SupplyDataContext	Runtime context for supplyData() nodes	packages/core/src/execution-engine/node-execution-context/supply-data-context.ts
BaseExecuteContext	Shared context functionality	packages/core/src/execution-engine/node-execution-context/base-execute-context.ts
Request/Response handling	AI tool execution	packages/core/src/execution-engine/requests-response.ts
Partial execution utils	Dirty node detection, graph traversal	packages/core/src/execution-engine/partial-execution-utils/
Interface definitions	Type system	packages/workflow/src/interfaces.ts

Sources: packages/core/src/execution-engine/workflow-execute.ts1-100 packages/core/src/execution-engine/node-execution-context/