node cookbook
n8n Merge Node: Combine Branches Without Losing Fields or Mismatching Items
Use the Merge node when a workflow needs to combine data from multiple branches, pair records, append streams, or reconnect paths after branching.
Independent third-party notes. n8n is a trademark of its owner and is referenced only for compatibility and troubleshooting context.
Quick Answer
Use the Merge node when a workflow needs to combine data from multiple branches, pair records, append streams, or reconnect paths after branching.
Problem Pattern
The user wants to reconnect workflow paths, but output shape and item matching can break downstream logic.
Key Facts
- Node role
- Combine data from multiple workflow inputs.
- Best fit
- Rejoining IF branches, combining lookup results, and pairing related data.
- Common risk
- Input item counts and matching strategy affect output shape.
- Common companion nodes
- IF, Set, Code, HTTP Request, database nodes, and app nodes.
Recommended Steps
- Decide whether you are appending, pairing, or matching data.
- Connect both branches or data sources to the Merge node.
- Choose the merge mode that matches the desired output shape.
- Inspect the output item count and fields after a test run.
- Add Set or Code nodes if downstream data needs normalization.
Verification
- The output item count matches the intended merge strategy.
- Fields from each input are present where downstream nodes expect them.
- Empty or missing input cases are handled safely.
Warnings
- Merge output can surprise you if the two inputs have different item counts.
- Do not assume fields from both inputs exist on every output item without testing.
Common Mistakes
- Using Merge to fix branching without checking item pairing.
- Expecting item order to be a reliable unique identifier.
- Losing fields because both inputs use the same key names.
- Skipping a test with empty results from one branch.
Examples
Input 1: original lead data
Input 2: enriched company data
Merge: combine by matching email or company domain
Output: lead plus enrichment fieldsFAQ
Why did Merge create fewer items than expected?
The selected mode may pair or match items rather than append all items. Check merge mode and input counts.
Should I merge by position or by key?
Use a stable key when records have an identifier. Position-based merging is easier to break when inputs are filtered or sorted.