Error «Multiple matching items» en n8n: cómo vincular los datos

Si te has metido en el mundo de la automatización, es muy probable que en algún momento te hayas topado con el dichoso mensaje de error «Multiple matching items» en n8n. Este error puede ser un verdadero quebradero de cabeza, especialmente cuando crees que tu flujo está bien montado pero, de repente, un nodo que antes funcionaba empieza a dar fallos sin sentido aparente.

Básicamente, lo que está pasando es que n8n se ha hecho un lío con la vinculación de elementos. Cuando intentas traer un dato de un nodo que está muy atrás en el camino, la herramienta intenta seguir el rastro del elemento actual hacia atrás, pero si en medio hay nodos que han mezclado o resumido la información, el sistema no sabe a cuál de todos los posibles candidatos referirse.

¿Por qué aparece este error exactamente?

Para entender este problema, hay que saber que n8n utiliza un concepto llamado item linking. Es como un hilo invisible que conecta cada dato que sale de un nodo con el dato que lo originó en el nodo anterior. Mientras el flujo sea lineal, todo va sobre ruedas. Sin embargo, el problema surge cuando usamos nodos que combinan múltiples entradas para crear una sola salida.

Por ejemplo, si utilizas un nodo de Merge, Summarize o Aggregate, estás rompiendo esa línea recta. Imagina que el nodo Merge junta datos de dos ramas distintas; el elemento resultante ya no tiene un único «padre», sino que puede estar relacionado con varios. Cuando más adelante en el flujo usas la expresión $(node_name).item, n8n intenta seguir el hilo, encuentra varias coincidencias posibles y, al no saber cuál elegir, lanza el error para evitar procesar datos incorrectos.

Casos comunes donde ocurre el fallo

¿Cuándo se da el error «Multiple matching items» en n8n? Un escenario muy típico es cuando tienes un flujo complejo con Google Sheets y Gmail. Imagina que descargas varios correos, procesas sus adjuntos y luego haces una consulta en una hoja de cálculo. Si después de ese paso intentas volver a referenciar el ID del mensaje original de Gmail usando .item, es muy probable que el nodo de Google Sheets haya alterado la estructura de los elementos, provocando que n8n vea múltiples ítems coincidentes para una sola ejecución.

Otro caso frustrante es cuando el nodo que referenciamos está en una rama distinta del flujo. Si dos caminos se unen pero los elementos mantienen sus identidades separadas, el nodo final podría intentar acceder a una información que pertenece a la rama A mientras procesa un elemento que vino de la rama B. En este caso, la expresión suele devolver null o dar un error de rama no encontrada.

Cómo solucionar el problema de raíz

Si te encuentras en este jardín, no te desesperes, que hay varias formas de salir airosamente. La más rápida es dejar de confiar en la magia automática de .item y empezar a ser específico con la posición del dato que necesitas. En lugar de dejar que n8n adivine, puedes usar métodos de indexación manual.

• Usar .first(): Ideal si sabes que el dato que necesitas está siempre en el primer elemento del nodo anterior, independientemente de cuántos haya.
• Usar .last(): Útil para pillar el dato más reciente de una lista.
• Usar .all()[index]: Esta es la opción más potente, ya que te permite acceder a cualquier posición exacta (por ejemplo, .all()[0] para el primero) mediante un índice numérico.

Otra alternativa es revisar la arquitectura de tu flujo. A veces, basta con reorganizar los nodos para que la referencia se haga justo antes de que los datos pasen por un nodo de agregación o fusión. Si mueves el nodo que falla a una posición previa al Merge, el hilo de vinculación seguirá intacto y el error desaparecerá por completo.

Dominar la gestión de los elementos en n8n es fundamental para crear automatizaciones robustas. La clave está en entender que, aunque la herramienta intenta facilitarnos la vida con el emparejamiento automático, hay situaciones donde la ambigüedad de los datos obliga al desarrollador a indicar manualmente la ruta exacta del ítem, evitando así que el flujo se detenga por una confusión en la trazabilidad de la información.