n8n Item Linking Explained | How Data Flows Between Nodes in n8n

Understanding Item Linking in n8n: How Data Flows Between Nodes

In this tutorial, you will learn the crucial concept of item linking in n8n and why it is essential for handling complex workflows, especially when working with large data sets and transformations. You will explore how n8n maintains the relationship between input and output data items across nodes, what can break this linking, and how to fix and maintain proper data flow throughout your workflows.

This knowledge is vital for avoiding unexpected results and errors when building advanced automations. For a deeper dive into how data is structured and flows in n8n, consider reviewing Understanding Data in n8n.

What Is Item Linking in n8n?

In n8n, each piece of data processed by a node is called an item. Nodes receive one or more items as input, operate on them, and output new items.

Item linking refers to the automatic connection n8n maintains between input items and their corresponding output items as data moves through the workflow. This linking allows downstream nodes to correctly reference and manipulate data from upstream nodes.

When Does n8n Automatically Link Items?

• Single input, single output: Linking is straightforward; the output items correspond directly to the input items.
• Single input, multiple outputs: All outputs link back to the single input.
• Multiple inputs and multiple outputs with equal counts: n8n links items in order—output item 1 links to input item 1, output item 2 to input item 2, and so forth. Even if you reorder input items, n8n attempts to maintain correct linking.

When Does Item Linking Break?

Item linking breaks in situations such as:

• Outputting a completely new set of items unrelated to input items.
• The number of output items differs from the number of input items.
• Using nodes like the Code node, Merge node, or Split node improperly, causing item order or count mismatches.

When linking breaks, downstream nodes cannot determine which input item corresponds to which output item, leading to errors or unexpected behavior.

Exploring Item Linking with a Practical Example

Let's dive into an example workflow to see item linking in action and understand how to maintain it.

Step 1: Generate Snack Items with a Code Node

You start with a manual trigger and a Code node generating 10 snack items. Each item has fields like id, product, brand, and category:

[
  { "id": "01", "product": "potato chips", "brand": "Lays", "category": "chips" },
  { "id": "02", "product": "nacho chips", "brand": "Doritos", "category": "chips" },
  { "id": "03", "product": "cheese balls", "brand": "Cheetos", "category": "chips" },
  // ... 7 more items
]

The Code node outputs these items following n8n's required data structure, wrapped inside a JSON object with the json property.

Step 2: Filter Items by Category Using IF Node

Next, an IF node filters only items where category equals "chips". After this, only 3 items remain, and the item linking is maintained because the filtered output items correspond to their original input items.

Step 3: Use Set Node to Combine Brand and Product

A Set node uses an expression to concatenate the brand and product names:

We love {{$json["brand"]}} {{$json["product"]}}

This node still maintains item linking since it modifies existing items without changing their count or order.

Step 4: Generate New Data in a Code Node (Breaking Item Linking)

Now, you use another Code node to generate a new set of items based on the filtered input. This new output contains only the productName and productReview fields and only for items where the category is "chips".

const items = [];
for (let i = 0; i < input.length; i++) {
  if (input[i].json.category === 'chips') {
    items.push({
      json: {
        productName: input[i].json.product,
        productReview: 'New data for item ' + i,
      },
      pairedItem: {
        item: i, // This is added later to fix linking
      },
    });
  }
}
return items;

At this point, item linking breaks because:

• The output items are a new array unrelated to the original input items.
• The number of output items (3) does not match the original input items (10).
• n8n cannot automatically determine which output item corresponds to which input item.

Step 5: Consequences of Broken Item Linking

If you try to reference data from previous nodes (e.g., brand or product) in downstream nodes after this broken linking, you get errors like:

Paired item data for item node generate dummy reviews random is unavailable

This happens because downstream nodes cannot determine which input item the current item corresponds to.

How to Fix Broken Item Linking in the Code Node

To fix this, you must explicitly set the pairedItem property in the output items to point back to the original input item index. This tells n8n how to link new output items to their corresponding input items.

Example Fix in Code Node

Modify your output items like this:

const items = [];
for (let i = 0; i < input.length; i++) {
  if (input[i].json.category === 'chips') {
    items.push({
      json: {
        productName: input[i].json.product,
        productReview: 'New data for item ' + i,
      },
      pairedItem: {
        item: i, // Link this output item to input item i
      },
    });
  }
}
return items;

Now, when you run this node, n8n will maintain the correct item linking, allowing downstream nodes to access previous item data without errors. For more details on how to use the Aggregate node to combine or summarize data after such transformations, check out the n8n Merge node documentation and the official n8n Aggregate node documentation{:target="_blank"}.

Item Linking with the Merge Node: Avoiding Data Corruption

The Merge node is another common point where item linking can break if not configured correctly.

Problem Scenario: Combining by Position

Suppose you have:

• Input 1: 3 filtered snack items.
• Input 2: 4 dummy review items.

Using the Merge node in Combine mode with "Merge by Position" will pair items by their array position — first item of input 1 with first item of input 2, second with second, etc.

If the order or length of inputs differs, this causes mismatches and corrupts your data. For example:

• "ID 1 potato chips" linked to "cheese balls" review.
• "Nacho chips" linked to "potato chips" review.

Solution: Merge by Matching Fields

Instead of merging by position, use "Merge by Matching Fields":

1. Set Mode to Combine.
2. Choose "Merge by Matching Fields".
3. Enable "Fields have different names" if the field names differ between inputs.
4. Specify the matching fields, e.g., product in input 1 and productName in input 2.

This ensures items are merged only when the matching fields are equal, preserving correct item linking and data integrity. For a detailed walkthrough on the Merge node, see Merge Node in n8n.

Step-by-Step Guide to Maintaining Item Linking

1. Understand your input and output item counts
   Ensure the number of output items matches the input items or explicitly link them.

2. Use pairedItem in Code nodes when generating new output items that don’t directly correspond to input items.

3. Avoid merging by position in the Merge node when input data orders or lengths differ.

4. Merge by matching fields in the Merge node to link items based on unique identifiers or matching properties.

5. Test your nodes frequently to check if item linking is preserved (green indicators in the UI and no errors referencing paired items).

6. Use expressions carefully to reference data from previous nodes, ensuring the item linking is intact.

If you are working with loops in your workflow, consider how item linking interacts with iterative processing by reviewing Loop Over Items in n8n.

Troubleshooting Common Issues with Item Linking

Practical Code Snippet: Using pairedItem in a Code Node

// Input data: array of items
const input = items;

// Prepare output array
const output = [];

for (let i = 0; i < input.length; i++) {
  if (input[i].json.category === 'chips') {
    output.push({
      json: {
        productName: input[i].json.product,
        productReview: `Review for item ${i}`,
      },
      pairedItem: {
        item: i, // Link back to input item index
      },
    });
  }
}

return output;

Useful n8n Documentation Links

• Working with Items and Expressions{:target="_blank"}
• Code Node Documentation{:target="_blank"}
• Merge Node Documentation{:target="_blank"}

Quick Reference: Item Linking Cheat Sheet

By mastering item linking in n8n, you ensure your workflows remain robust, data stays consistent, and your automations run smoothly without unexpected errors. As shown in the video above, understanding and controlling data flow between nodes is key to building advanced and reliable n8n workflows.