Las 5 comprobaciones que dicen si un flujo en JSON va a importar de verdad
La razón más común por la que una plantilla falla no es un error de la plantilla: es que nadie la
ejecutó antes de venderla. Este es el checklist exacto que usamos —con los números de nuestra propia
prueba de extremo a extremo en dos versiones limpias de n8n— para revisar cualquier .json
en diez minutos, antes de pagar por él o de culparte por una importación rota.
1. ¿Existen los tipos de nodo en tu instancia?
Un flujo en JSON es una lista de nodos, cada uno con un type como
n8n-nodes-base.httpRequest o n8n-nodes-base.removeDuplicates. Si tu instancia no
conoce un tipo, el nodo entra como bloque desconocido y la cadena muere ahí. El catálogo se consulta:
GET {N8N_URL}/types/nodes.json # una entrada por nombre de nodo y por grupo de versiónLa trampa: ese archivo trae varias entradas por nombre de nodo, y la última suele ser la más antigua. Un script que se queda con la última reporta versiones que no existen y nodos «desconocidos» que están perfectamente. Hay que tomar el máximo de todas las entradas de cada nombre. En nuestra instancia de prueba (n8n 2.43.6, 559 tipos instalados) los dos archivos resolvieron 28/28 nodos · 0 tipos desconocidos.
2. ¿Cada typeVersion cabe en tu versión de n8n?
Cada nodo declara además typeVersion. Compáralo con el máximo que ofrece tu instancia. Lo que hay
que saber es qué pasa cuando es más alto, porque la respuesta honesta no es «se rompe».
Probamos en el borde exacto de la promesa de compatibilidad —«n8n 1.60 o superior»— en un contenedor
limpio de n8n 1.60.0. Tres nodos declaraban una versión por encima del máximo de esa versión:
removeDuplicates v2 (máx. 1.1), readWriteFile v1.1 (máx. 1) y
respondToWebhook v1.4 (máx. 1.1). n8n los resolvió con la versión más nueva que tenía y
todos ejecutaron bien: 0 tipos ausentes, 13/13 nodos en verde. O sea: una versión por encima
del máximo es una advertencia, no una sentencia — pero es exactamente el caso que hay que haber
probado antes de prometer soporte. Si alguien te dice «funciona en 1.60+», pide la corrida en 1.60.
3. ¿Hay datos fijados (pinData) en el archivo?
pinData congela la salida de un nodo para poder demostrar un flujo sin llamar a ninguna API. En un
archivo que estás evaluando es peligroso por una razón concreta: el flujo parece funcionar y
produce resultados preciosos sin hablar con nada. Abre el JSON y busca pinData. Si está, bórralo y
vuelve a correr: la segunda corrida es la prueba real.
4. ¿Las credenciales son marcadores y no hay nada escrito a mano?
Dos fallos en direcciones opuestas. Un nodo que trae un bloque credentials con un id de
la instancia del autor importa limpio y falla al ejecutar con «credentials not found». Un nodo con una clave de
API escrita en un header o en la URL es peor: se filtra al importar y es invisible hasta que lees campo por
campo. Busca en el archivo credentials, apiKey, Bearer,
sk- y AIza. Nuestro propio empaquetador falla si algún nodo contiene una clave escrita
a mano — esa aserción es una de las pruebas que viajan dentro del kit.
5. ¿Cuántos nodos son ejecutables y cuántos son carteles?
«14 nodos» y «13 nodos» pueden describir el mismo archivo. Las notas adhesivas (los bloques amarillos de anotación) son nodos en el JSON: cuentan en el archivo y no hacen nada al ejecutar. Nuestro flujo de prospección es 14 nodos en total, 13 ejecutables + 1 nota adhesiva. Pide el número de ejecutables y verifícalo en el archivo. Es una comprobación de dos líneas y te dice si el vendedor contó o copió.
Extra — el nodo con estado que hace ver roto un flujo que funciona
Si el flujo usa RemoveDuplicates en modo «entries», las claves vistas se guardan por
workflowId en la base de la instancia (tabla processed_data). Córrelo una vez: 3
items. Córrelo otra vez con la misma entrada: 0 items, sin error, la cadena se detiene. Ese cero determinista
en la segunda corrida no es un bug: es memoria. Antes de juzgar un flujo, córrelo en una instancia desechable o
limpia el historial de deduplicación. Le dedicamos un post-mortem aparte, porque nos costó un día.
El protocolo de 10 minutos
1. grep -c '"type"' archivo.json # conteo de nodos (ejecutables + notas)
2. grep 'pinData' archivo.json # vacío = bien
3. grep -E '(apiKey|Bearer|sk-|AIza)' archivo.json # vacío = bien
4. versión máxima por tipo desde /types/nodes.json # 0 desconocidos = bien
5. docker run --rm n8nio/n8n:latest # importar + ejecutar
n8n import:workflow --input=archivo.json
n8n execute --id=<id> --rawOutput # mirar lastNodeExecuted
Dos notas de haberlo hecho de verdad: en n8n 1.60 el CLI espera que --input sea un
array de flujos (workflows.map is not a function si le pasas un objeto suelto), y
n8n execute no acepta --file: importa primero y ejecuta por --id. Además,
usa un contenedor desechable: ejecutar n8n execute dentro de un contenedor que ya está sirviendo
falla con Task Broker's port 5679 is already in use.
Cómo se ve una corrida que pasa
No «importó». Una corrida que pasa es: todos los nodos en success,
lastNodeExecuted igual al nodo que esperas y un artefacto de salida con el número de filas
correcto. En nuestro caso: 13/13 nodos en verde, lastNodeExecuted: 11 - Enviar a tu webhook/CRM y
un CSV real de 1.529 bytes con 4 filas aptas de 11 negocios. Los servicios externos se
sustituyeron por mocks locales; los nodos de lógica corrieron verbatim, que es donde vive el riesgo real.
Este checklist no es texto de marketing: es la batería de pruebas que viaja dentro del kit. El paquete Pro
incluye TESTING.md con la evidencia completa — cada versión, cada nodo, cada número.
Ver qué incluye →