Execution Engine v2

Relevant source files

The following files were used as context for generating this wiki page:

• packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts
• packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts
• packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts
• packages/workflow/src/common/index.ts (Referenced via graph traversal utilities)
• packages/nodes-base/AGENTS.md
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts

The Execution Engine v2 governs how n8n workflows process data through a graph of interconnected nodes. It manages item cardinality, branching logic, and data transformation across different node types, including programmatic, declarative, and AI-specific components. The engine ensures that each node executes once per input item unless specific flow control settings, such as executeOnce: true, are applied.

Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:40-42, packages/nodes-base/AGENTS.md:12-25

Core Execution Model

The engine follows an item-based execution pattern. When a trigger or node outputs multiple items, the engine runs every downstream node once for each item. This behavior is modified by flow control nodes that aggregate or split item sets.

Data Flow and Cardinality

The engine processes data as a series of JSON items. If a node returns $N$ items, the subsequent node executes $N$ times. To prevent unintended item multiplication (e.g., when fetching from independent sources), the engine provides specific mechanisms:

• executeOnce: true: Forces a node to run exactly once regardless of the number of input items.
• Parallel Branching: Allows independent processing paths that merge later.
• Merge Node: Combines items from parallel branches using modes such as append or combineByPosition.

Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:79-115, packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:40-42

Item Processing Flow

The following diagram illustrates the standard item-based execution versus the executeOnce override.

The diagram shows how cardinality propagates through the graph.
Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:88-100

Node Implementation Types

The engine supports several implementation patterns for nodes, each defining how the engine interacts with the node's logic.

Node Type	Implementation Key	Description
Programmatic	execute()	Contains custom JavaScript/TypeScript logic for data manipulation.
Declarative	requestDefaults	Defines API interactions via routing configuration without manual code.
Trigger (Webhook)	webhook()	Responds to external HTTP requests; includes lifecycle methods like checkExists.
Trigger (Polling)	poll()	Periodically checks external services; uses static data to persist state.

Sources: packages/nodes-base/AGENTS.md:12-25

Workflow Architecture Patterns

The engine enables complex graph structures through specialized flow control nodes.

Branching and Routing

The engine evaluates conditions to route items through specific paths.

• IF Node: Performs binary branching based on true/false conditions.
• Switch Node: Routes items through multiple outputs based on rules or expressions.
• Convergence: When branches rejoin, the engine uses optional chaining in expressions or Set nodes to normalize data.

Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:133-145, packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:153-157

AI and Agentic Execution

The engine supports AI-specific execution flows, particularly for Large Language Models (LLMs) and multi-agent systems.

This diagram shows the relationship between AI Agents, Models, and Tools.
Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:60-72

Error Handling and Resilience

The engine provides two primary layers of error management to ensure execution continuity.

Node-Level Settings

The engine respects specific configuration on individual nodes to handle failures:

• onError: Can be set to continueRegularOutput or continueErrorOutput.
• retryOnFail: Re-executes the node if it fails.
• maxTries and waitBetweenTries: Configures the retry strategy.

Workflow-Level Triggers

• Error Trigger Node: The engine automatically invokes this node if any part of the workflow fails.
• Error Workflows: A dedicated separate workflow can be assigned as the error handler via settings.errorWorkflow.

Sources: packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts:117-128

Knowledge Base and Ingestion

The engine manages data ingestion for Vector Databases, splitting large documents into manageable chunks for semantic search.

1. Fetch: Retrieves binary data (e.g., from Google Drive or S3).
2. Load & Split: Uses a DocumentDefaultDataLoader and a TextSplitter to create chunks (typically 500-1000 characters).
3. Embed: Generates vectors using an embedding model.
4. Upsert: Stores chunks in a Vector Store (e.g., Pinecone, Supabase) with unique IDs.

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts:25-45

Summary

Execution Engine v2 provides a robust, item-centric framework for workflow automation. By combining standard programmatic execution with specialized AI orchestration and detailed error handling, it enables scalable and resilient data processing across diverse integration scenarios.