n8n out of memory : diagnostic et correction sur VPS

Pourquoi n8n crashe en mémoire, et pas pour la raison qu'on croit

Signaux qui confirment un crash OOM n8n

• Message de sortie exact : FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory dans les logs du conteneur (docker logs n8n)
• Crash silencieux sous systemd : le service redémarre automatiquement sans laisser de trace si Restart=always est actif — vérifier journalctl -u n8n --since "1 hour ago"
• OOM kill du noyau : dmesg | grep -i oom montre Killed process <pid> (node) avant le redémarrage, indépendamment de Node
• Corrélation avec un workflow lourd : le crash survient toujours pendant les exécutions de type « traitement de fichier » ou « boucle sur plusieurs milliers d'items »
• Heap stable pendant des heures puis pic soudain : un workflow déclenché périodiquement accumule des closures non libérées — le heap monte à chaque run et ne redescend pas complètement
• Charge mémoire normale sur htop : la RAM système n'est pas saturée au moment du crash, ce qui confirme que le problème est V8, pas la machine

Prérequis avant d'intervenir

Corriger l'OOM : du diagnostic à la configuration stable

1. 01

   Confirmer la cause dans les logs

   Lisez les 200 dernières lignes du conteneur au moment du crash :

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

   Si vous voyez FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory, c'est un crash V8. Si vous voyez Killed seul sans message Node, c'est l'OOM killer du noyau — les deux peuvent coexister sur le même incident.

2. 02

   Poser le plafond V8 dans la variable NODE_OPTIONS

   Dans votre docker-compose.yml, ajoutez la variable d'environnement NODE_OPTIONS sur le service n8n. La valeur recommandée selon la RAM du VPS :

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

   Règle : réserver environ la moitié de la RAM disponible après système d'exploitation et services annexes (Redis, proxy). Ne pas dépasser 70 % de la RAM totale.

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

   Attention : Ne mettez pas NODE_OPTIONS à l'intérieur d'un span de backticks dans vos fichiers .env si vous utilisez la substitution de variables — la valeur doit être une chaîne littérale.

3. 03

   Vérifier que la valeur est bien prise en compte

   Après docker compose up -d, vérifiez que Node lit bien le plafond :

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

   La valeur affichée doit approcher votre --max-old-space-size. Si elle affiche encore 512 ou 1500, la variable d'environnement n'est pas transmise au processus — vérifiez que NODE_OPTIONS est dans la section environment: du service, pas dans env_file: avec une valeur mal parsée.

4. 04

   Passer en mode queue avec Redis

   Le mode main (défaut) exécute tout dans un seul processus. Pour les instances qui traitent plus de 20 workflows simultanés ou des payloads volumineux, séparez les rôles :

   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:

   Le service n8n devient le main process (API + interface + webhooks) avec un plafond modéré. Le service n8n-worker prend en charge les exécutions avec un plafond plus généreux. La directive scale: 2 lance deux workers — ajustez selon vos besoins.

5. 05

   Séparer le webhook process si le trafic l'exige

   Sur les instances qui reçoivent beaucoup de webhooks en parallèle, le main process peut être saturé même sans exécuter de workflows. n8n propose un mode webhook dédié :

     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"

   Configurez ensuite votre reverse proxy pour router /webhook/ vers le port 5679 et le reste vers le port 5678 du main process. Le mode webhook est disponible depuis n8n 1.0.

6. 06

   Activer le garbage collector explicite pour les workflows lourds

   Pour les workflows qui traitent des fichiers volumineux ou des boucles longues, vous pouvez aider V8 à libérer la mémoire plus agressivement :

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

   Cette option expose global.gc() — n8n peut l'appeler entre les étapes d'un workflow. À combiner avec le paramètre EXECUTIONS_DATA_SAVE_ON_SUCCESS=none si vous n'avez pas besoin de l'historique d'exécution : les données d'exécution conservées en mémoire représentent souvent 30 à 50 % du heap.

7. 07

   Surveiller le heap après correction

   Installez un endpoint de métriques n8n pour observer l'évolution du heap sans avoir à intervenir à la main :

   N8N_METRICS=true
   N8N_METRICS_PREFIX=n8n_

   L'endpoint /metrics (port 5678) expose alors nodejs_heap_size_used_bytes et nodejs_heap_size_total_bytes, compatibles Prometheus. Un dashboard Grafana basique sur ces deux métriques vous alertera bien avant le prochain crash.

Configuration post-correction : variables d'environnement utiles

Dépannage — erreurs réelles et leurs causes

Ressources et prochaines étapes