Introduction

In real n8n workflows you rarely have a single straight line of execution. More often you fork the flow: one branch queries your CRM, another fetches analytics, a third waits for a webhook from a customer. At some point you need to bring those parallel branches back together — and that is exactly what the Merge node is for. Understanding how to combine branches correctly prevents data loss, duplicate processing, and silent bugs that only show up in production.

This lesson covers the three main merge strategies in n8n: waiting for all inputs, merging by a matching key (SQL-style join), and appending (concatenating) all incoming items. Each strategy serves a different purpose, and picking the wrong one is one of the most common mistakes when building non-trivial automations.

How the Merge Node Works

The Merge node takes multiple input streams (Input 1, Input 2, optionally more) and produces a single output stream. It executes only when every connected input has delivered at least one item, which means it implicitly synchronizes the branches. This is the "wait" behavior: no matter how fast one branch finishes, the Merge node pauses until the slowest branch arrives.

You can also add a timeout in the node settings. If one branch never completes, the merge will eventually stop waiting and either drop the data or continue with whatever arrived. This matters for long-running workflows where one external API might hang.

Merge by Key (Join Behavior)

This is the closest equivalent to a SQL JOIN. You pick a field (e.g. `email` or `orderId`) that exists in both input streams, and the node pairs up items that share the same value. Items without a match are dropped by default, but you can configure the mode to behave like a LEFT JOIN (keep unmatched items from Input 1) or an outer join.

The result is one item per match, with fields from both inputs combined. The dropdown options are:

Append: concatenates all items from both inputs into a flat list, in order, without pairing. Use this when the branches produce independent records that should just be processed together later (for example, all contacts from Mailchimp and all contacts from HubSpot queued for a single deduplication step).

Merge By Key: pairs items on a shared field, like a database join. Use this when each item on one side logically relates to one item on the other side, such as matching an order record with its corresponding payment record.

Wait: the simplest mode — it does no transformation, just synchronizes timing. Output items follow Input 1's order, and Input 2's items are simply attached one-to-one by position. Use this only when you control both branches and know the order matches.

The Mode dropdown has these four options: Append, Merge By Key, Merge By Position, and Wait. Note that "Merge By Position" is the technical name for the simple wait-and-pair behavior — it pairs items by their index in the input array, which only works correctly when both branches have the same number of items in the same order.

Practical Example: Combining Order and Payment Data

Imagine Branch 1 pulls orders from a database, and Branch 2 pulls payment status from Stripe. Each branch produces items with an `orderId` field. You want one combined record per order.

{
  "node": "Merge",
  "type": "n8n-nodes-base.merge",
  "parameters": {
    "mode": "mergeByKey",
    "joinMode": "inner",
    "propertyName1": "orderId",
    "propertyName2": "orderId"
  }
}

With `joinMode` set to `inner`, only orders that exist in both branches end up in the output. If you switch to `left`, orders that have no payment record yet still flow downstream, marked as unmatched — useful for spotting missing payments.

Common Mistakes and Gotchas

The most frequent error is using "Merge By Position" when the two branches produce a different number of items. If Branch 1 returns 10 orders and Branch 2 returns only 7 payment records, 3 of the order items will either pair with `null` payment data or get silently dropped depending on settings. Always use "Merge By Key" when counts can differ.

Another gotcha: the Merge node does not deduplicate. If Branch 1 has the same email twice and Branch 2 once, you can get duplicate joined rows. Deduplication must happen before the merge, or with a separate node after.

Finally, remember that Merge waits for every connected input. If you forget to connect one input, the node will wait forever (or until timeout). Unconnected inputs are a common cause of workflows that hang in production.

Summary

The Merge node is the synchronization point of any multi-branch workflow. Use Append when you simply want to stack independent lists, Merge By Key when items on each side relate by a shared identifier, and Wait / Merge By Position only when both branches produce matched arrays of the same length. Always verify every input is connected, choose a join mode that matches your data integrity needs, and place deduplication outside the merge to avoid surprises.