Errores Comunes en n8n y Cómo Solucionarlos (Guía de Troubleshooting)

Errores comunes n8n soluciones es uno de los usos más prácticos de n8n. Cuando empiezas a trabajar con n8n, es normal encontrar errores y situaciones inesperadas. En esta guía de troubleshooting recogemos los errores más frecuentes en n8n y cómo solucionarlos de forma rápida y efectiva.

1. Error: «The node returned an error» (Error en un nodo)

Es el error más común. Aparece cuando un nodo no puede ejecutarse correctamente. Las causas más frecuentes son:

• Credenciales incorrectas o expiradas: Verifica que tus credenciales siguen siendo válidas. Los tokens OAuth expiran periódicamente.
• Campos requeridos vacíos: El nodo necesita un campo que está vacío o no se ha mapeado correctamente.
• API externa caída: El servicio externo puede estar temporalmente inaccesible.

Solución: Haz clic en el nodo con error para ver el mensaje de error detallado. Esto te dará pistas claras sobre qué está fallando.

2. El webhook no recibe datos

Si usas un Webhook Trigger y no llegan datos, verifica:

• ¿Está el workflow activo? Los webhooks solo funcionan cuando el workflow está activado.
• ¿Estás usando la URL de producción (no la de prueba)? La URL de prueba solo funciona cuando estás en modo «Test».
• ¿El servicio externo está enviando las peticiones al método correcto (POST, GET)?
• ¿Tu servidor n8n es accesible desde internet? Si está detrás de un firewall, los webhooks externos no llegarán.

3. Error de credenciales: «401 Unauthorized» o «403 Forbidden»

Estos errores indican problemas de autenticación:

• 401 Unauthorized: Las credenciales son incorrectas o han expirado. Reconecta la integración.
• 403 Forbidden: Tienes credenciales válidas pero no tienes permisos para esa acción específica. Verifica los scopes/permisos de tu app.

4. El nodo «Code» devuelve un error de sintaxis

Si usas el nodo Code con JavaScript, los errores de sintaxis son frecuentes. Recuerda:

• El código debe devolver siempre un array de items: return items; o return [{json: {resultado: 'valor'}}];
• Usa $input.all() para acceder a todos los items de entrada
• Usa $input.first().json para acceder al primer item
• Los errores de JavaScript muestran el número de línea donde ocurrió el problema

5. El flujo se ejecuta pero no hace nada (items vacíos)

Este es un error difícil de detectar porque el flujo «funciona» sin errores pero no produce resultados. La causa suele ser que un nodo intermedio devuelve 0 items.

Cómo diagnosticarlo: Activa el modo «Always Output Data» en los nodos y revisa cuántos items pasan entre cada nodo en los logs de ejecución.

6. Error «ECONNREFUSED» o problemas de conexión

Este error aparece cuando n8n no puede conectarse a un servicio externo:

• Verifica que el servicio externo está funcionando
• Comprueba que la URL o host configurado es correcto
• Si el servicio está en tu red local, verifica que n8n puede acceder a esa red
• Revisa las reglas de firewall de tu servidor

7. n8n consume demasiada memoria o CPU

En instalaciones self-hosted, n8n puede consumir muchos recursos si tienes flujos que procesan grandes cantidades de datos:

• Limita el número de items que procesas en cada ejecución
• Usa paginación cuando leas datos de APIs o bases de datos
• Aumenta la memoria RAM del servidor si es necesario
• Revisa los logs de n8n para identificar qué workflow consume más recursos

8. El Schedule Trigger no se ejecuta

Si tu flujo programado no se ejecuta en el horario esperado:

• Verifica que el workflow está activado (no en borrador)
• Comprueba la zona horaria configurada en n8n y en el trigger (puede haber diferencias)
• Revisa los logs de ejecuciones para ver si hay errores

¿Dónde buscar ayuda adicional?

Si no encuentras solución a tu problema:

• Foro oficial de n8n: community.n8n.io — la comunidad es muy activa y responde rápido
• Documentación oficial: docs.n8n.io — está muy completa
• n8n Hispano: Puedes contactarnos con tu duda específica