JavaScript heap out of memory: cómo solucionar problemas de memoria en n8n

El error "JavaScript heap out of memory" ocurre en n8n cuando una ejecución de flujo de trabajo requiere más memoria de la que tiene disponible el proceso Node.js de n8n. Las causas más comunes son archivos binarios grandes, grandes volúmenes de datos JSON, el nodo Code, así como ejecuciones manuales en las que n8n mantiene adicionalmente una copia de los datos para la interfaz. El problema se puede resolver asignando más memoria al proceso n8n a través de la variable de entorno NODE_OPTIONS con el parámetro --max-old-space-size, cambiando el procesamiento de datos binarios al modo del sistema de archivos, y mediante Execution-Pruning periódico, que elimina automáticamente datos de ejecución antiguos. Estado: julio de 2026.

¿Por qué n8n reporta el error "JavaScript heap out of memory"?

El error ocurre porque n8n, como una aplicación Node.js, utiliza de forma predeterminada solo una cantidad limitada de memoria para el llamado tamaño de heap del motor V8 y este límite se excede en flujos de trabajo intensivos en memoria.

Según la documentación oficial de n8n sobre cómo resolver problemas de memoria, los requisitos de memoria de una ejecución dependen principalmente de la cantidad de datos JSON, el tamaño de los datos binarios, la cantidad de ejecuciones simultáneas y el uso del nodo Code. Las ejecuciones manuales a través del editor también aumentan el consumo porque n8n mantiene adicionalmente una copia de los datos para la vista en vivo en el frontend.

• Grandes volúmenes de datos: Muchos objetos JSON o archivos binarios grandes por ejecución.
• Nodo Code: La lógica de JavaScript personalizada puede aumentar significativamente el consumo de memoria.
• Ejecución manual: Copia de datos adicional para la pantalla en vivo en el editor.
• Ejecuciones paralelas: Múltiples flujos de trabajo que se ejecutan simultáneamente se suman.

¿Cómo proporciona más memoria a n8n a través de NODE_OPTIONS?

Aumenta la memoria utilizable pasando el parámetro --max-old-space-size con un límite de memoria más alto en megabytes al proceso Node.js a través de la variable de entorno NODE_OPTIONS.

Según la documentación, cuando ocurre un error "JavaScript heap out of memory", vale la pena aumentar el llamado área Old-Memory del motor V8, ya sea a través de la línea de comandos o a través de NODE_OPTIONS. Para instancias autohospedadas, esto significa prácticamente: establece NODE_OPTIONS con el valor --max-old-space-size=4096, por ejemplo, para asignar aproximadamente cuatro gigabytes de memoria heap antigua al proceso, e inicia n8n nuevamente después. Lo importante es: esta configuración solo funciona si el servidor o contenedor tiene realmente suficiente memoria física disponible. Si no es suficiente, la documentación recomienda equipar la instancia con más recursos en general, o elegir un plan más grande en n8n Cloud.

¿Cómo previene problemas de memoria con datos binarios?

n8n almacena datos binarios como archivos, imágenes o PDFs directamente en la memoria de forma predeterminada, lo que hace que los archivos grandes causen fallos rápidamente si no cambia el modo de almacenamiento al sistema de archivos.

Según la documentación sobre tratamiento de datos binarios, n8n almacena datos binarios en la memoria de forma predeterminada, lo que puede causar fallos con archivos grandes. A través de la variable de entorno N8N_DEFAULT_BINARY_DATA_MODE, puede cambiar el modo a filesystem para que n8n escriba los datos en el disco en su lugar. En modo Queue, el modo de sistema de archivos no es compatible según la documentación; en su lugar, se utiliza el modo de base de datos. Importante saber: la limpieza de datos binarios también se ejecuta a través del modelo de almacenamiento activo respectivo. Si cambia el modo, los datos antiguos permanecen en la ubicación de almacenamiento anterior hasta que se eliminen manualmente.

¿Cómo ayuda Execution-Pruning a reducir el creciente consumo de memoria?

Execution-Pruning elimina automáticamente las ejecuciones completadas junto con sus datos de ejecución y datos binarios asociados según la antigüedad o la cantidad, evitando que la base de datos y la memoria crezcan sin control.

Según la documentación sobre gestión de datos de ejecución, Pruning está activado de forma predeterminada y se activa cuando una ejecución es más antigua que el valor de EXECUTIONS_DATA_MAX_AGE en horas (predeterminado: 336 horas, es decir, 14 días) o cuando el número total de ejecuciones excede el valor de EXECUTIONS_DATA_PRUNE_MAX_COUNT (predeterminado: 10.000). Las ejecuciones en ejecución, en espera o nuevas, así como las ejecuciones marcadas con etiquetas o valoraciones, nunca se eliminan. Además, un búfer de seguridad a través de la variable EXECUTIONS_DATA_HARD_DELETE_BUFFER (predeterminado: una hora) garantiza que pueda ver las ejecuciones completadas recientemente mientras se libera memoria en segundo plano.

• EXECUTIONS_DATA_PRUNE: Activa la limpieza automática, está activa de forma predeterminada.
• EXECUTIONS_DATA_MAX_AGE: Elimina ejecuciones por antigüedad en horas, predeterminado 336.
• EXECUTIONS_DATA_PRUNE_MAX_COUNT: Limita el número total de ejecuciones almacenadas, predeterminado 10.000.

¿Qué ajustes de flujo de trabajo reducen el consumo de memoria?

Además de la configuración del lado del servidor, la forma más efectiva de reducir el consumo de memoria es directamente en el diseño del flujo de trabajo, procesando datos en porciones más pequeñas en lugar de cargar todo a la vez.

La documentación de n8n recomienda específicamente dividir datos en bloques más pequeños, procesar aproximadamente 200 en lugar de 10.000 registros por ejecución, evitar el nodo Code cuando sea posible y ejecutar mediante un disparador en lugar de manualmente cuando se trata de grandes volúmenes de datos. Para volúmenes de datos muy grandes, la documentación sugiere dividir el flujo de trabajo con los nodos Loop-Over-Items y Execute-Workflow en sub-flujos de trabajo, de modo que solo los datos del lote actual se mantengan en la memoria y se liberen posteriormente. Si utiliza n8n en producción para automatizaciones más complejas y no desea implementar estos puntos de ajuste por su cuenta, NordFlux lo apoya en la configuración y aseguramiento de flujos de trabajo n8n incluyendo la configuración del servidor apropiada.

Preguntas frecuentes sobre problemas de memoria en n8n

¿Cuánta memoria debe tener como mínimo un servidor n8n?

La documentación no especifica un valor mínimo fijo, sino que indica que la necesidad depende de la cantidad de datos y la cantidad de ejecuciones paralelas. En la práctica, debe proporcionar suficiente memoria para que el max-old-space-size establecido a través de NODE_OPTIONS también esté cubierto físicamente, de lo contrario, el problema se desplaza.

¿Resuelve una configuración NODE_OPTIONS más alta cada problema de memoria?

No, un límite de heap más alto solo proporciona más búfer, pero no soluciona la causa raíz como flujos de trabajo ineficientes o datos binarios crecientes sin control. Según la documentación, también debe reducir la cantidad de datos por ejecución y mantener Execution-Pruning activo para que el consumo de memoria se mantenga bajo control de forma permanente.

¿Qué sucede si desactivo Execution-Pruning?

Sin Pruning, las ejecuciones completadas junto con los datos de ejecución y datos binarios se acumulan sin límite en la base de datos. Esto conduce, según la documentación, a largo plazo a un consumo de memoria creciente, razón por la cual n8n activa la limpieza de forma predeterminada.

¿Por qué ocurre el error principalmente en ejecuciones manuales?

Porque n8n, en una ejecución manual a través del editor, mantiene adicionalmente una copia de los datos de ejecución para la pantalla en vivo en el frontend. Con grandes volúmenes de datos, esto aumenta notablemente el consumo de memoria, razón por la cual la documentación recomienda ejecutar procesaciones extensas a través de un disparador en lugar de manualmente.