n8n out of memory: diagnóstico y corrección en VPS

Por qué n8n falla por memoria, y no por la razón que crees

Señales que confirman un crash OOM en n8n

• Mensaje de salida exacto: FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory en los logs del contenedor (docker logs n8n)
• Crash silencioso bajo systemd: el servicio se reinicia automáticamente sin dejar rastro si Restart=always está activo — comprobar con journalctl -u n8n --since "1 hour ago"
• OOM kill del kernel: dmesg | grep -i oom muestra Killed process <pid> (node) antes del reinicio, independientemente de Node
• Correlación con un workflow pesado: el crash ocurre siempre durante ejecuciones de tipo «procesamiento de archivo» o «bucle sobre miles de elementos»
• Heap estable durante horas y luego pico repentino: un workflow lanzado periódicamente acumula closures no liberadas — el heap sube en cada ejecución y no baja completamente
• Carga de memoria normal en htop: la RAM del sistema no está saturada en el momento del crash, lo que confirma que el problema es V8, no la máquina

Requisitos previos antes de intervenir

Corregir el OOM: del diagnóstico a la configuración estable

1. 01

   Confirmar la causa en los logs

   Lee las últimas 200 líneas del contenedor en el momento del crash:

   docker logs n8n --tail 200 2>&1 | grep -E "FATAL|heap|OOM|Killed"

   Si ves FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory, es un crash V8. Si ves Killed solo sin mensaje Node, es el OOM killer del kernel — ambos pueden coexistir en el mismo incidente.

2. 02

   Establecer el límite V8 mediante NODE_OPTIONS

   En tu docker-compose.yml, añade la variable de entorno NODE_OPTIONS al servicio n8n. Valor recomendado según la RAM del VPS:

   - VPS 4 GB: --max-old-space-size=2048
   - VPS 8 GB: --max-old-space-size=4096
   - VPS 16 GB: --max-old-space-size=8192

   Regla: reserva aproximadamente la mitad de la RAM disponible tras el sistema operativo y servicios auxiliares (Redis, proxy). No superar el 70% de la RAM total.

   services:
     n8n:
       image: n8nio/n8n:latest
       environment:
         - NODE_OPTIONS=--max-old-space-size=4096
         # ... otras variables

3. 03

   Verificar que el valor se lee correctamente

   Tras docker compose up -d, verifica que Node lee el límite:

   docker exec n8n node -e "const v8=require('v8'); console.log(v8.getHeapStatistics().heap_size_limit / 1024 / 1024, 'MB')"

   El valor mostrado debe aproximarse a tu --max-old-space-size. Si sigue mostrando 512 o 1500, la variable de entorno no se está pasando al proceso — verifica que NODE_OPTIONS está en la sección environment: del servicio.

4. 04

   Cambiar al modo queue con Redis

   El modo main (predeterminado) ejecuta todo en un único proceso. Para instancias que gestionan más de 20 workflows simultáneos o payloads voluminosos, separa los roles:

   services:
     redis:
       image: redis:7-alpine
       restart: unless-stopped
       volumes:
         - redis_data:/data
   
     n8n:
       image: n8nio/n8n:latest
       environment:
         - NODE_OPTIONS=--max-old-space-size=2048
         - EXECUTIONS_MODE=queue
         - QUEUE_BULL_REDIS_HOST=redis
         - QUEUE_BULL_REDIS_PORT=6379
       depends_on:
         - redis
       ports:
         - "5678:5678"
   
     n8n-worker:
       image: n8nio/n8n:latest
       command: worker
       environment:
         - NODE_OPTIONS=--max-old-space-size=4096
         - EXECUTIONS_MODE=queue
         - QUEUE_BULL_REDIS_HOST=redis
         - QUEUE_BULL_REDIS_PORT=6379
       depends_on:
         - redis
       scale: 2
   
   volumes:
     redis_data:

   El servicio n8n se convierte en el proceso principal (API + UI + webhooks) con un límite moderado. El servicio n8n-worker gestiona las ejecuciones con un límite mayor. La directiva scale: 2 lanza dos workers — ajusta según tus necesidades.

5. 05

   Separar el proceso webhook si el tráfico lo requiere

   En instancias que reciben muchos webhooks en paralelo, el proceso principal puede saturarse incluso sin ejecutar workflows. n8n ofrece un modo webhook dedicado:

     n8n-webhook:
       image: n8nio/n8n:latest
       command: webhook
       environment:
         - NODE_OPTIONS=--max-old-space-size=1024
         - EXECUTIONS_MODE=queue
         - QUEUE_BULL_REDIS_HOST=redis
         - QUEUE_BULL_REDIS_PORT=6379
         - N8N_DISABLE_UI=true
       depends_on:
         - redis
       ports:
         - "5679:5678"

   Configura tu reverse proxy para enrutar /webhook/ al puerto 5679 y el resto al puerto 5678 del proceso principal. El modo webhook está disponible desde n8n 1.0.

6. 06

   Activar el garbage collector explícito para workflows pesados

   Para workflows que procesan archivos grandes o bucles largos, puedes ayudar a V8 a liberar memoria de forma más agresiva:

   NODE_OPTIONS="--max-old-space-size=4096 --expose-gc"

   Esto expone global.gc() — n8n puede llamarlo entre los pasos de un workflow. Combínalo con EXECUTIONS_DATA_SAVE_ON_SUCCESS=none si no necesitas el historial de ejecución: los datos de ejecución retenidos suelen representar el 30-50% del heap.

7. 07

   Monitorizar el heap tras la corrección

   Activa las métricas de n8n para observar la evolución del heap sin intervención manual:

   N8N_METRICS=true
   N8N_METRICS_PREFIX=n8n_

   El endpoint /metrics (puerto 5678) expone nodejs_heap_size_used_bytes y nodejs_heap_size_total_bytes, compatibles con Prometheus. Un dashboard básico de Grafana sobre estas dos métricas te alertará mucho antes del próximo crash.

Configuración post-corrección: variables de entorno útiles

Resolución de problemas — errores reales y sus causas

Recursos y próximos pasos