The n8n Merge node is one of the most powerful — and most confusing — nodes in n8n. It lets you combine data from multiple workflow branches into a single stream. But it has five different modes, each with different behavior, and picking the wrong one causes silent failures that are hard to debug.
This guide covers every Merge mode with concrete examples, a decision tree for picking the right one, and a free workflow JSON you can import directly.
Why the Merge Node Exists
Most n8n workflows have a single data stream: one trigger → one set of nodes → one output. But real-world automations often need to:
- Wait for two parallel API calls to finish, then combine their results
- Join data from two different sources (like a CRM record + its related deals)
- Process items in two branches based on an If node, then rejoin them
- Sync data where you want only items that exist in both sources
The Merge node handles all of these — but you have to know which mode to use.
The Five Merge Modes
1. Append
What it does: Combines all items from Input 1 and Input 2 into one list. Input 1 items come first, then Input 2 items.
When to use: You have two separate lists and want to process them together. Common after an If node where both branches need the same downstream processing.
Gotcha: Append does not deduplicate. If the same item appears in both inputs, you get it twice.
2. Combine by Position
What it does: Merges item 1 from Input 1 with item 1 from Input 2, item 2 with item 2, and so on. Pairs items by index position.
When to use: You have two arrays of the same length that correspond positionally — e.g., user IDs from one API and profile data from another, both in the same order.
Gotcha: If inputs have different lengths, the longer one gets truncated. Always verify both inputs have the same count.
3. Combine by Fields (SQL-style Join)
What it does: Joins items from Input 1 and Input 2 based on matching field values. You specify which field to match on.
Sub-modes:
- Inner Join — only items where the key exists in BOTH inputs
- Left Join — all Input 1 items, with matching Input 2 data merged in
- Outer Join — all items from both inputs, joined where possible
Gotcha: Field names are case-sensitive. Email and email will not match.
4. Choose Branch
What it does: Passes through items from only one input, discarding the other.
When to use: You processed items in two branches and only want to continue with one.
Gotcha: This discards data permanently.
5. Cross Join (All Combinations)
What it does: Creates every possible combination of items from Input 1 and Input 2. 3 items x 4 items = 12 output items.
When to use: Generating all combinations of two lists — e.g., all size+color combinations for a product catalog.
Gotcha: Output size grows exponentially. 100 x 100 = 10,000 items.
Decision Tree: Which Mode?
Combine all items into one list?
→ Append
Same-length arrays, merge fields positionally?
→ Combine by Position
Shared key field (email, ID, order_id)?
→ Combine by Fields
All from both? → Outer Join
Only matches? → Inner Join
All Input 1 + matches? → Left Join
Only need one branch?
→ Choose Branch
Every combination?
→ Cross Join
Common Mistake: Connecting Only One Input
The Merge node waits for both inputs before processing. Connect only one input and the workflow hangs indefinitely.
Fix: Make sure both Input 1 (top) and Input 2 (bottom) connection points have a node connected. Check the Merge node input panel — you will see separate tabs for Input 1 and Input 2 with item counts.
Free Workflow JSON: Parallel API Calls + Merge
This workflow calls two APIs in parallel and merges the results. Import by pasting on the n8n canvas (Ctrl+V):
{
"name": "Parallel API Merge Demo",
"nodes": [
{
"parameters": { "httpMethod": "POST", "path": "merge-demo" },
"name": "Webhook",
"type": "n8n-nodes-base.webhook",
"typeVersion": 2,
"position": [240, 300]
},
{
"parameters": { "url": "https://jsonplaceholder.typicode.com/users/1", "options": {} },
"name": "Get User Profile",
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 4,
"position": [480, 160]
},
{
"parameters": { "url": "https://jsonplaceholder.typicode.com/todos?userId=1", "options": {} },
"name": "Get User Todos",
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 4,
"position": [480, 440]
},
{
"parameters": { "mode": "combine", "combinationMode": "mergeByPosition", "options": {} },
"name": "Merge Results",
"type": "n8n-nodes-base.merge",
"typeVersion": 3,
"position": [720, 300]
}
],
"connections": {
"Webhook": { "main": [[{"node": "Get User Profile", "type": "main", "index": 0}, {"node": "Get User Todos", "type": "main", "index": 0}]] },
"Get User Profile": { "main": [[{"node": "Merge Results", "type": "main", "index": 0}]] },
"Get User Todos": { "main": [[{"node": "Merge Results", "type": "main", "index": 1}]] }
}
}
Uses JSONPlaceholder (free, no auth needed). Swap in your real API URLs.
Need Production-Ready Workflows?
If you want pre-built, documented workflows that handle edge cases out of the box:
→ n8n Workflow Starter Pack ($29 one-time) — Lead Capture → CRM, Stripe Payment → Fulfillment, Form → Sheets + Slack. Each includes a setup guide and test checklist.
First workflow is free — drop a comment and I will share the JSON.
Summary
| Mode | Use when |
|---|---|
| Append | Combine two lists into one |
| Combine by Position | Same-length arrays, positionally paired |
| Combine by Fields | Shared key field (SQL JOIN) |
| Choose Branch | Only need one branch |
| Cross Join | Every combination (watch size) |
The Merge node unlocks workflows that linear pipelines cannot handle. Once you know the five modes, it becomes one of your most useful nodes.
Drop a comment if you hit a Merge node issue — happy to debug.
Top comments (1)
Which Merge mode trips you up most? Drop a comment and I will share the free workflow JSON for the Parallel API demo above (paste directly into n8n canvas). Also happy to debug any specific Merge node issue you are hitting.