Lesson 25 · 3. Deep Dive Concepts · Last updated · By Dheeraj Sharma

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

Learn n8n Item Linking Explained | How Data Flows Between Nodes in n8n in this comprehensive n8n tutorial. Step-by-step guide with video, code examples, and expert tips from the n8n Zero to Hero course.

Table of Contents

Overview

This lesson is part of the n8n AI Automation - Zero to Hero course, Section: 3. Deep Dive Concepts.

Watch the video above for the full tutorial, or read the written guide below.

What is n8n item linking and why does it matter?

Item linking (also called data linking) is n8n's mechanism for tracking which output items originated from which input items as data flows through a workflow. n8n maintains this chain automatically in most scenarios: a single input always links to its output, and multiple outputs all link back to a single input. When that chain breaks, downstream nodes lose access to ancestor data and throw "paired item data unavailable" errors that stall the workflow.

How to fix broken item linking in n8n Code nodes and Merge nodes

Item linking breaks inside a Code node when the number of output items differs from the number of input items, or when the node constructs entirely new item objects. For example, filtering 10 snack items down to 3 and producing a new product_review field for each means n8n can no longer automatically trace which output came from which input. The fix is to add a pairedItem property to each output object and set its value to the index of the corresponding input item, for instance pairedItem: i where i is the loop counter. n8n reads that field to re-establish the chain, converting red expression previews to green in all downstream nodes.

The Merge node introduces a different failure mode. Its "combine by position" mode pairs items strictly by their order in each branch. If two branches produce items in different sequences, positional merging silently joins the wrong records. A snacks branch ordered by ID and a reviews branch in a different order will cross-link cheese-ball reviews to nacho-chips data. The correct fix is to switch the Merge node to "on matching fields" mode and name the field that uniquely identifies records on both sides.

When the matching field carries different names in each input branch, for example product on one side and product_name on the other, enable the "fields to match have different names" setting and map each side explicitly. After this change, the Merge node joins cheese balls to cheese balls and nacho chips to nacho chips regardless of the order items arrive in either branch.

Key Takeaways

  • Item linking is n8n's provenance chain: each output item references the input item it came from, which is what lets a node read fields from nodes several steps earlier in the workflow.
  • n8n breaks automatic linking in a Code node when output count differs from input count or when the code constructs brand-new item objects without pairedItem hints.
  • Fix broken Code node linking by adding pairedItem: <input_index> to every output object; n8n uses that field to reconnect the chain and resolve downstream expressions.
  • Merge node "combine by position" corrupts data silently when the two input branches deliver items in different orders; use "on matching fields" and specify a shared identifier instead.
  • The "paired item data unavailable" error and red expression previews in downstream nodes are the diagnostic signals that item linking broke upstream, most often inside a Code node, Merge node, or Split node.

Next Steps

Continue your n8n journey with the full n8n AI Automation - Zero to Hero course.

Frequently Asked Questions

The 'paired item data unavailable' error means a downstream node cannot trace an output item back to the input item that produced it. n8n throws this when a Code node, Merge node, or Split node breaks the item-linking chain, typically by outputting a different number of items than it received or by constructing entirely new item objects without a `pairedItem` reference.

Add a `pairedItem` property to each object in the Code node's output array and set its value to the index of the corresponding input item. For example, write `pairedItem: i` where `i` is the loop counter. n8n reads that field to reconnect the output item to the correct input, restoring access to fields from all ancestor nodes and clearing 'paired item data unavailable' errors in downstream nodes.

n8n maintains item linking automatically when a node has a single input and a single output, when one input produces multiple outputs (all outputs link to that one input), or when the number of inputs equals the number of outputs and their order is preserved. Linking breaks when the counts differ, when a Code node creates entirely new item objects, or when items are reordered without `pairedItem` hints.

The Merge node's 'combine by position' mode pairs the first item from input one with the first item from input two regardless of content. If two branches produce items in different orders, positional merging silently joins the wrong records. Switching to 'on matching fields' mode and specifying a shared identifier, such as matching `product` on one branch to `product_name` on the other, ensures each item joins its correct counterpart.

Dheeraj Sharma

Dheeraj Sharma

AI Systems Builder
Creator of the n8n Zero to Hero course (42 lessons, 31+ hours). I help solopreneurs build AI systems that grow revenue without growing workload.

Get the n8n Mastery Bundle

All workflows, cheat sheets, and premium resources from the entire course in one package.

Get Premium Resources