PairedItem dans n8n : comprendre et corriger les erreurs de chaînage de données

Un workflow tourne parfaitement en test, node par node. Puis vous ajoutez un Merge, un Aggregate, ou un node Code qui résume plusieurs lignes en une seule — et une expression plus loin, qui fonctionnait la veille encore, se met à afficher Paired item data for item from node [nom] is unavailable ou, sur des instances plus anciennes, Referenced node is not part of input. La donnée est pourtant bien là, visible dans le panneau de sortie du node incriminé. Le problème n'est pas la donnée elle-même : c'est le fil invisible qui est censé la relier à sa source, et qui vient de casser.

Ce que n8n appelle vraiment pairedItem

Chaque item qui circule entre deux nodes n8n transporte deux choses : son contenu (json) et une métadonnée invisible dans l'éditeur, pairedItem, qui pointe vers l'item (ou les items) du node précédent dont il est directement issu. C'est cette chaîne, maillon par maillon depuis le déclencheur, qui permet à une expression comme {{ $('Classifier l'email').item.json.categorie }} de retrouver la bonne valeur même trois nodes plus loin, sans que vous ayez à recopier manuellement cette information à chaque étape.

Ce mécanisme n'est pas une bizarrerie propre à n8n : il reprend un problème bien identifié en informatique, celui de la provenance des données dans les systèmes de traitement en pipeline — savoir, pour un résultat donné, retracer exactement de quelles données sources il découle. Une étude de référence de Simmhan, Plale et Gannon, publiée en 2005 dans ACM SIGMOD Record, dresse un état des lieux de ces systèmes de provenance dans les workflows scientifiques distribués et souligne que cette traçabilité automatique est à la fois une fonctionnalité centrale et un point de fragilité récurrent dès que les flux de données cessent d'être strictement linéaires (Simmhan, Plale & Gannon, 2005, ACM SIGMOD Record). Un pairedItem cassé dans n8n est exactement cette même rupture de lignée, à l'échelle d'un workflow d'automatisation plutôt que d'un calcul scientifique distribué.

Tant qu'un workflow reste strictement linéaire — un item entre, un item sort, à chaque node — cette chaîne se construit toute seule et reste invisible. Le problème survient dès qu'un node casse la correspondance un-pour-un entre son entrée et sa sortie.

Les deux messages d'erreur qui signalent le même problème

Selon la version de n8n et l'endroit exact où la référence casse, deux formulations apparaissent pour la même cause profonde :

• Paired item data for item from node [X] is unavailable. Ensure [X] is providing the required output. — le message actuel, le plus courant : n8n sait qu'il doit retrouver un lien vers le node X, mais ne trouve aucun pairedItem exploitable dans les items qu'il a produits.
• Referenced node is not part of input — une formulation plus ancienne, rencontrée sur des versions antérieures ou dans certains contextes d'expression, pour la même incapacité à retracer la lignée jusqu'au node visé.

Dans les deux cas, la correction est identique : il faut soit rétablir la chaîne de pairedItem à la source, soit changer la façon dont vous référencez le node en aval.

Pourquoi la chaîne se rompt

Trois situations concentrent l'essentiel des cas rencontrés en pratique :

Un node Code qui agrège plusieurs items en un seul. Un node Code en mode Run Once for All Items qui calcule un total, une moyenne ou un résumé à partir de dix items d'entrée et ne retourne qu'un seul item de sortie ne peut pas, par défaut, savoir auquel des dix items d'entrée rattacher ce résultat unique. Sans intervention de votre part, n8n ne devine pas ce lien — le node doit le préciser lui-même.

Un node Merge en mode Combine avec des branches désalignées. Comme détaillé dans notre guide du node Merge, les modes Position et Matching Fields associent des items de deux entrées différentes. Dès qu'une branche a perdu des items en route (un IF, un Filter en amont), l'appariement peut devenir ambigu, et la lignée d'origine de l'item fusionné n'est plus un chemin unique et évident.

Un node Code qui reconstruit des items sans reporter le pairedItem. C'est la cause la plus fréquente. Dès qu'un node Code trie, filtre ou reconstruit son tableau de sortie plutôt que de le transformer item par item dans l'ordre, l'index de sortie ne correspond plus mécaniquement à l'index d'entrée — et sans pairedItem fixé explicitement, n8n perd le fil.

Réparer dans le node Code

Notre guide du node Code détaille le format items général ; voici précisément où placer pairedItem. Pour une transformation un-pour-un qui change l'ordre ou filtre des items :

const input = $input.all();
return input
  .filter(item => item.json.statut === "valide")
  .map(item => ({
    json: { ...item.json, traite: true },
    pairedItem: { item: input.indexOf(item) }
  }));

Pour une agrégation qui condense plusieurs items en un seul résultat, le pairedItem devient un tableau plutôt qu'un objet unique — vous listez tous les items d'entrée qui ont contribué au résultat :

const input = $input.all();
const total = input.reduce((somme, item) => somme + item.json.montant, 0);
return [{
  json: { total },
  pairedItem: input.map((_, index) => ({ item: index }))
}];

Cette seconde forme rétablit une lignée valide même quand la relation n'est plus un-pour-un : n8n sait alors que ce résultat unique dépend de l'ensemble des items d'entrée, et toute expression en aval qui cherche à remonter jusqu'à eux fonctionne à nouveau.

Contourner sans réparer la chaîne

Réparer pairedItem à la source est la solution la plus propre, mais elle suppose que vous ayez la main sur le node Code fautif. Ce n'est pas toujours le cas — après un node core comme Aggregate, Summarize, ou un Information Extractor en LangChain, par exemple. La solution de repli consiste à changer la façon dont vous accédez au node source dans l'expression qui échoue :

• $('Nom du node').first() — le premier item produit par ce node, quelle que soit la position de l'item courant.
• $('Nom du node').last() — le dernier.
• $('Nom du node').all()[2] — un index précis, quand vous savez exactement à quelle position se trouve la donnée recherchée.

Ces trois formes contournent volontairement la lignée automatique : elles fonctionnent par position plutôt que par filiation réelle. C'est parfaitement adapté quand le node source ne produit qu'un seul item pertinent (un total, une configuration), mais dangereux si plusieurs items différents peuvent s'y trouver selon l'exécution — vous obtiendriez alors silencieusement la mauvaise valeur plutôt qu'une erreur visible.

Cas pratique : retrouver l'identifiant document après un Aggregate RAG

Un pipeline d'ingestion documentaire type — comme celui détaillé dans notre guide du chunking pour le RAG — découpe un PDF en dizaines de chunks, calcule un embedding pour chacun, puis les regroupe avec un node Aggregate avant une insertion Supabase groupée. Si un node situé après cet Aggregate a besoin de retrouver l'identifiant du document d'origine via $('Lire le PDF').item, l'erreur apparaît presque systématiquement : l'Aggregate a produit un seul item à partir de dizaines, et la lignée vers un item source précis n'a plus de sens univoque.

La bonne pratique ici n'est pas de réparer le pairedItem de l'Aggregate, mais d'éviter d'en avoir besoin : incluez l'identifiant du document directement dans le json de chaque chunk, dès le node qui les crée, plutôt que d'aller le rechercher plus loin via la lignée. La donnée voyage alors avec l'item lui-même — la solution la plus robuste reste presque toujours de transporter l'information dont vous avez besoin, plutôt que de compter sur la lignée pour la retrouver après coup.

Pièges fréquents

• Considérer l'erreur comme un bug n8n : c'est un signal correct — la lignée est réellement ambiguë, et deviner à sa place produirait un résultat faux plutôt qu'une erreur visible.
• Utiliser .first() par réflexe partout : cela masque l'erreur sans garantir que la valeur récupérée est la bonne dès que le node source produit plusieurs items distincts.
• Oublier de fixer pairedItem après un tri ou un filtre dans un node Code, alors que le nombre d'items change bel et bien entre l'entrée et la sortie.
• Ne pas transporter l'information nécessaire dans le json de l'item, et compter sur la lignée pour la retrouver trois nodes plus loin — fragile dès qu'un Merge ou un Aggregate s'intercale.

Pour aller plus loin

Ce type de rupture de chaînage apparaît typiquement dans les pipelines qui combinent plusieurs branches ou regroupent des lots d'items — exactement les cas couverts par les workflows d'ingestion du Pack Assistant RAG (119 €), déjà construits pour transporter les identifiants nécessaires sans dépendre d'une lignée fragile après un Aggregate. Si vous construisez vos propres nodes Code, notre guide sur le node Merge et notre guide sur Split Out et Aggregate couvrent les deux autres nodes core qui cassent le plus souvent cette chaîne — de quoi repérer le problème avant qu'il n'apparaisse en production.