add info on item linking errors in expressions

docs/_redirects

@@ -168,7 +168,7 @@
 /code-examples/expressions/variables/   /code/builtin/
 /code-examples/javascript-functions/methods/   /code/builtin/
 /code-examples/javascript-functions/variables/  /code/builtin/
-/data/data-mapping/   /data/data-mapping/data-mapping-ui/
+/data/data-mapping/   /data/data-mapping/
 
 # Editor UI
 

docs/data/data-mapping/data-item-linking/item-linking-concepts.md

@@ -25,10 +25,19 @@ If a node doesn't control how to link input items to output items, n8n tries to
 
 If n8n can't link items automatically, and the node doesn't handle the item linking, n8n displays an error. Refer to [Item linking errors](/data/data-mapping/data-item-linking/item-linking-errors/) for more information.
 
-## An item linking example
+## Item linking example
+
+![A diagram showing the threads linking multiple items back through a workflow](/_images/data/data-mapping/data-item-linking/item-linking-multiple-lines.png)
+
+In this example, it's possible for n8n to link an item in one node back several steps, despite the item order changing. This means the node that sorts movies alphabetically can access information about the linked item in the node that gets famous movie actors.
+
+The methods for accessing linked items are different depending on whether you're using the UI, expressions, or the code node. Explore the following resources:
+
+* [Mapping in the UI](/data/data-mapping/data-mapping-ui/)
+* [Mapping in the expressions editor](/data/data-mapping/data-mapping-expressions/)
+* [Item linking in the Code node](/data/data-mapping/data-item-linking/item-linking-code-node/)
+* [Item linking errors](/data/data-mapping/data-item-linking/item-linking-errors/)
 
-![A diagram showing how you can track back from an item in your current node, to one in a previous node, even when items have been re-ordered](/_images/data/data-mapping/data-item-linking/item-linking.png)
 
-In this example, it's possible for n8n to link an item in the current node back several steps, despite the item order changing. This means the current node can access information about the linked item in the first node.
 
 

docs/data/data-mapping/data-item-linking/item-linking-errors.md

@@ -4,46 +4,48 @@
 
 # Item linking errors
 
-n8n displays errors related to data mapping when there are problems tracing an item's linked parent items back through the workflow.
+In n8n you can reference data from any previous node. This doesn't have to be the node just before: it can be any previous node in the chain. When referencing nodes further back, you use the expression syntax `$(node_name).item`. 
 
-## Errors when pinning data
+<figure markdown>
+![A diagram showing the threads linking multiple items back through a workflow](/_images/data/data-mapping/data-item-linking/item-linking-multiple-lines.png)
+<figcaption markdown>Diagram of threads for different items. Due to the item linking, you can get the actor for each movie using `$('Get famous movie actors).item`.</figcaption>
+</figure>
 
-If you see this error message:
-<!-- vale off -->
-> ERROR: '`<node-name>`' must be unpinned to execute
-<!-- vale on -->
-Unpin the data in the named node, and execute the node to get fresh data.
+Since the previous node can have multiple items in it, n8n needs to know which one to use. When using `.item`, n8n figures this out for you behind the scenes. Refer to [Item linking concepts](/data/data-mapping/data-item-linking/item-linking-concepts/) for detailed information on how this works.
+
+`.item` fails if information is missing. To figure out which item to use, n8n maintains a thread back through the workflow's nodes for each item. For a given item, this thread tells n8n which items in previous nodes generated it. To find the matching item in a given previous node, n8n follows this thread back until it reaches the node in question.
+
+When using `.item`, n8n displays an error when:
+
+- The thread is broken
+- The thread points to more than one item in the previous node (as it's unclear which one to use)
 
-This error has two possible causes:
+To solve these errors, you can either avoid using `.item`, or fix the root cause.
 
-* The number of inputs into the pinned node has changed since you pinned it.
-* You've edited the pinned data and changed the number of items.
+You can avoid `.item` by using `.first()`, `.last()` or `.all()[index]` instead. They require you to know the position of the item that you’re targeting within the target node's output items. Refer to [Built in methods and variables | Output of other nodes](/code/builtin/output-other-nodes/) for more detail on these methods.
 
+The fix for the root cause depends on the exact error.
 
-## Errors when using the Code node
+### Fix for 'Info for expressions missing from previous node'
 
 If you see this error message:
 
-> ERROR: Can't get data for expression under '`<field-name>`' field
+> ERROR: Info for expression missing from previous node
 
-You need to supply item linking information yourself, because you have an item linking scenario that n8n can't automatically handle.
+There's a node in the chain that doesn't return pairing information. The solution here depends on the type of the previous node:
 
-To control item linking, set `pairedItem` when returning data. For example, to link to the item at index 0:
+- Code nodes: make sure you return which input items the node used to produce each output item. Refer to [Item linking in the code node](/data/data-mapping/data-item-linking/item-linking-code-node/) for more information.
+- Custom or community nodes: the node creator needs to be update the node to return which input items it uses to produce each output item. Refer to [Item linking for node creators](/data/data-mapping/data-item-linking/item-linking-node-building/) for more information.
 
-```js
-[
-	{
-		"json": {
-			. . . 
-		},
-		// The index of the input item that generated this output item
-		"pairedItem": 0
-	}
-]
-```
+### Fix for 'Multiple matching items for expression'
 
+This is the error message:
 
-Refer to [Item linking concepts](/data/data-mapping/data-item-linking/item-linking-concepts/) for a conceptual understanding of item linking, and [Manage item linking in the Code node](/data/data-mapping/data-item-linking/item-linking-code-node/) for detailed guidance on handling item linking.
+> ERROR: Multiple matching items for expression
 
+Sometimes n8n uses multiple items to create a single item. Examples include the Summarize, Aggregate, and Merge nodes. These nodes can combine information from multiple items.
 
+When you use `.item` and there are multiple possible matches, n8n doesn't know which one to use. To solve this you can either:
 
+- Use `.first()`, `.last()` or `.all()[index]` instead. Refer to [Built in methods and variables | Output of other nodes](/code/builtin/output-other-nodes/) for more detail on these methods.
+- Reference a different node that contains the same information, but doesn't have multiple matching items.

docs/data/data-mapping/data-mapping-expressions.md

@@ -0,0 +1,94 @@
+---
+contentType: howto
+---
+
+# Mapping in the expressions editor
+
+These examples show how to access linked items in the expressions editor. Refer to [expressions](/code/expressions/) for more information on expressions, including built in variables and methods.
+
+For information on errors with mapping and linking items, refer to [Item linking errors](/data/data-mapping/data-item-linking/item-linking-errors/).
+
+## Access the linked item in a previous node's output
+
+When you use this, n8n works back up the item linking chain, to find the parent item in the given node.
+
+```js
+// Returns the linked item
+{{$("<node-name>").item}}
+```
+
+As a longer example, consider a scenario where a node earlier in the workflow has the following output data:
+
+```json
+[
+  {
+    "id": "23423532",
+    "name": "Jay Gatsby",
+  },
+  {
+    "id": "23423533",
+    "name": "José Arcadio Buendía",
+  },
+  {
+    "id": "23423534",
+    "name": "Max Sendak",
+  },
+  {
+    "id": "23423535",
+    "name": "Zaphod Beeblebrox",
+  },
+  {
+    "id": "23423536",
+    "name": "Edmund Pevensie",
+  }
+]
+```
+
+To extract the name, use the following expression:
+
+```js
+{{$("<node-name>").item.json.name}}
+```
+
+
+### Access the linked item in the current node's input
+
+In this case, the item linking is within the node: find the input item that the node links to an output item.
+
+```js
+// Returns the linked item
+{{$input.item}}
+```
+
+As a longer example, consider a scenario where the current node has the following input data:
+
+```json
+[
+  {
+    "id": "23423532",
+    "name": "Jay Gatsby",
+  },
+  {
+    "id": "23423533",
+    "name": "José Arcadio Buendía",
+  },
+  {
+    "id": "23423534",
+    "name": "Max Sendak",
+  },
+  {
+    "id": "23423535",
+    "name": "Zaphod Beeblebrox",
+  },
+  {
+    "id": "23423536",
+    "name": "Edmund Pevensie",
+  }
+]
+```
+
+To extract the name, you'd normally use drag-and-drop [Data mapping](/data/data-mapping/), but you could also write the following expression:
+
+```js
+{{$input.item.json.name}}
+```

docs/data/data-mapping/data-mapping-ui.md

@@ -11,6 +11,7 @@ You can map data in the following ways:
 * Using the expressions editor.
 * By dragging and dropping data from the **INPUT** into parameters. This generates the expression for you.
 
+For information on errors with mapping and linking items, refer to [Item linking errors](/data/data-mapping/data-item-linking/item-linking-errors/).
 
 ## How to drag and drop data
 
@@ -64,91 +65,3 @@ n8n displays it in table form like this:
 
 !["Screenshot of a table in the INPUT panel. It includes a top level field named "nested." This field contains nested data, which is indicated in bold."](/_images/data/data-mapping/nested-data.png)
 
-## Map data in the expressions editor
-
-These examples show how to access linked items in the expressions editor. Refer to [expressions](/code/expressions/) for more information on expressions, including built in variables and methods.
-
-### Access the linked item in a previous node's output
-
-When you use this, n8n works back up the item linking chain, to find the parent item in the given node.
-
-```js
-// Returns the linked item
-{{$("<node-name>").item}}
-```
-
-As a longer example, consider a scenario where a node earlier in the workflow has the following output data:
-
-```json
-[
-  {
-    "id": "23423532",
-    "name": "Jay Gatsby",
-  },
-  {
-    "id": "23423533",
-    "name": "José Arcadio Buendía",
-  },
-  {
-    "id": "23423534",
-    "name": "Max Sendak",
-  },
-  {
-    "id": "23423535",
-    "name": "Zaphod Beeblebrox",
-  },
-  {
-    "id": "23423536",
-    "name": "Edmund Pevensie",
-  }
-]
-```
-
-To extract the name, use the following expression:
-
-```js
-{{$("<node-name>").item.json.name}}
-```
-
-
-### Access the linked item in the current node's input
-
-In this case, the item linking is within the node: find the input item that the node links to an output item.
-
-```js
-// Returns the linked item
-{{$input.item}}
-```
-
-As a longer example, consider a scenario where the current node has the following input data:
-
-```json
-[
-  {
-    "id": "23423532",
-    "name": "Jay Gatsby",
-  },
-  {
-    "id": "23423533",
-    "name": "José Arcadio Buendía",
-  },
-  {
-    "id": "23423534",
-    "name": "Max Sendak",
-  },
-  {
-    "id": "23423535",
-    "name": "Zaphod Beeblebrox",
-  },
-  {
-    "id": "23423536",
-    "name": "Edmund Pevensie",
-  }
-]
-```
-
-To extract the name, you'd normally use drag-and-drop [Data mapping](/data/data-mapping/), but you could also write the following expression:
-
-```js
-{{$input.item.json.name}}
-```

docs/data/data-mapping/index.md

@@ -8,5 +8,5 @@ Data mapping means referencing data from previous nodes.
 
 This section contains guidance on:
 
-* Mapping data in most scenarios: [Data mapping](/data/data-mapping/data-mapping-ui/)
+* Mapping data in most scenarios: [Data mapping in the UI](/data/data-mapping/data-mapping-ui/) and [Data mapping in expression](/data/data-mapping/data-mapping-expressions/)
 * How to handle [item linking](/data/data-mapping/data-item-linking/) when using the Code node or building your own nodes. 

docs/data/index.md

@@ -17,7 +17,7 @@ This section covers:
 * [Transforming data](/data/transforming-data/)
 * [Process data using code](/data/code/)
 * [Pinning](/data/data-pinning/) and [editing](/data/data-editing/) data during workflow development.
-* [Data mapping](/data/data-mapping/data-mapping-ui/) and [Item linking](/data/data-mapping/data-item-linking/): how data items link to each other.
+* [Data mapping](/data/data-mapping/) and [Item linking](/data/data-mapping/data-item-linking/): how data items link to each other.
 
 ## Related resources
 

mkdocs.yml

@@ -214,6 +214,7 @@ nav:
       - Data mapping: 
         - data/data-mapping/index.md
         - Data mapping in the UI: data/data-mapping/data-mapping-ui.md
+        - Data mapping in the expressions editor: data/data-mapping/data-mapping-expressions.md
         - Data item linking: 
           - data/data-mapping/data-item-linking/index.md
           - Item linking concepts: data/data-mapping/data-item-linking/item-linking-concepts.md