Skip to main content

N8N Multiple Items and Item Referencing Documentation

Overview

When referencing data from previous nodes in n8n, you must account for whether you're processing single or multiple items. Using the wrong reference method will cause errors like "Can't determine which item to use" or "Paired item data is unavailable."

The Problem

N8N workflows can process multiple items simultaneously (batch processing). When a node outputs multiple items and you need to reference that data in a downstream node, n8n needs to know which specific item you're referring to for each iteration.

Reference Methods

Method 1: Singular Item Reference (.item)

Syntax:

{{ $('Node Name').item.json.property }}

When to use:

  • When the referenced node outputs only 1 item
  • When "Execute Once" is checked on nodes, limiting output to a single item
  • In simple workflows where you're certain only one item will ever be processed

Limitations:

  • Fails with multiple items - Will produce "[Can't determine which item to use]" error
  • Not suitable for batch processing scenarios

Example:

{{ $('Crawl Primary URL').item.json.results[0].title }}

✅ Works when "Crawl Primary URL" outputs 1 item
❌ Fails when "Crawl Primary URL" outputs 22 items

Method 2: Explicit Item Index (Recommended for Multiple Items)

Syntax:

{{ $('Node Name').all()[$itemIndex].json.property }}

When to use:

  • When the referenced node outputs multiple items
  • When you need to maintain 1-to-1 correspondence between items from different nodes
  • For batch processing scenarios where items flow through multiple nodes
  • This method works in ALL scenarios - both single and multiple items

How it works:

  • .all() retrieves all items from the referenced node
  • [$itemIndex] selects the item at the current iteration's position
  • Maintains paired relationship between items across nodes

Example:

{{ $('Crawl Primary URL').all()[$itemIndex].json.results[0].links.internal.map(link => link.href) }}

✅ Works when "Crawl Primary URL" outputs 1 item
✅ Works when "Crawl Primary URL" outputs 22 items
✅ Maintains correct item pairing in batch operations

Method 3: $item() Function

Syntax:

{{ $item('Node Name').json.property }}

When to use:

  • Similar to Method 2, designed for multiple items
  • Shorter syntax alternative

Note: This method may not work consistently in all n8n versions or node types. If it fails, use Method 2 (Explicit Item Index) instead.

Common Use Cases

HTTP Request Nodes with Body Parameters

When sending data from a previous node in an HTTP request body:

❌ Wrong (fails with multiple items):

{
  "urls": {{ $('Previous Node').item.json.links }}
}

✅ Correct (works with any number of items):

{
  "urls": {{ $('Previous Node').all()[$itemIndex].json.links }}
}

Set Node or Code Node

When transforming data from upstream nodes:

✅ Always use explicit item index for reliability:

{{ $('Source Node').all()[$itemIndex].json.data }}

Best Practices

  1. Default to Explicit Item Index: Use $('Node Name').all()[$itemIndex] as your standard reference method - it works in all scenarios

  2. Use .item only when certain: Only use the singular .item reference when you're absolutely certain the node will always output exactly 1 item

  3. Test with multiple items: Always test workflows with multiple items, not just single items, to catch referencing errors early

  4. Check "Execute Once" settings: Be aware of nodes with "Execute Once" enabled, as they artificially limit output to 1 item and may hide referencing issues

  5. Maintain item correspondence: When items flow through multiple nodes, ensure each downstream reference uses [$itemIndex] to maintain the correct 1-to-1 relationship

Quick Reference Table

Scenario Method Syntax Works?
Single item output Singular $('Node').item.json.prop ✅
Single item output Explicit Index $('Node').all()[$itemIndex].json.prop ✅
Multiple items output Singular $('Node').item.json.prop ❌
Multiple items output Explicit Index $('Node').all()[$itemIndex].json.prop ✅
Batch processing Singular $('Node').item.json.prop ❌
Batch processing Explicit Index $('Node').all()[$itemIndex].json.prop ✅

Error Messages Indicating This Issue

If you see these errors, use the Explicit Item Index method:

  • "Can't determine which item to use"
  • "Paired item data for item from node 'X' is unavailable"
  • "Ensure 'X' is providing the required output"

Solution: Replace .item with .all()[$itemIndex] in your expressions.

Back to top