n8n out of memory: diagnosis and fix on a VPS

Why n8n crashes on memory, and not for the reason you think

Signals that confirm an n8n OOM crash

• Exact exit message: FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory in container logs (docker logs n8n)
• Silent crash under systemd: the service restarts automatically without leaving a trace if Restart=always is set — check journalctl -u n8n --since "1 hour ago"
• Kernel OOM kill: dmesg | grep -i oom shows Killed process <pid> (node) before the restart, independently of Node
• Correlation with a heavy workflow: the crash always occurs during executions of type "file processing" or "loop over thousands of items"
• Heap stable for hours then sudden spike: a periodically triggered workflow accumulates unreleased closures — the heap rises on each run and does not fully come back down
• Normal memory load in htop: system RAM is not saturated at the time of the crash, confirming the problem is V8, not the machine

Prerequisites before intervening

Fixing OOM: from diagnosis to stable configuration

1. 01

   Confirm the cause in logs

   Read the last 200 lines of the container at the time of the crash:

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

   If you see FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory, it is a V8 crash. If you see Killed alone without a Node message, it is the kernel OOM killer — both can coexist on the same incident.

2. 02

   Set the V8 cap via NODE_OPTIONS

   In your docker-compose.yml, add the NODE_OPTIONS environment variable to the n8n service. Recommended value based on VPS RAM:

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

   Rule: reserve roughly half the RAM available after the operating system and ancillary services (Redis, proxy). Do not exceed 70% of total RAM.

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

3. 03

   Verify the value is actually read

   After docker compose up -d, verify Node reads the cap:

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

   The displayed value should be close to your --max-old-space-size. If it still shows 512 or 1500, the environment variable is not being passed to the process — verify that NODE_OPTIONS is in the environment: section of the service, not in env_file: with a badly parsed value.

4. 04

   Switch to queue mode with Redis

   main mode (default) runs everything in a single process. For instances handling more than 20 simultaneous workflows or large payloads, separate the 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:

   The n8n service becomes the main process (API + UI + webhooks) with a moderate cap. The n8n-worker service handles executions with a higher cap. The scale: 2 directive starts two workers — adjust to your needs.

5. 05

   Separate the webhook process if traffic requires it

   On instances receiving many parallel webhooks, the main process can be saturated even without executing workflows. n8n offers a dedicated webhook mode:

     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"

   Then configure your reverse proxy to route /webhook/ to port 5679 and the rest to port 5678 of the main process. Webhook mode is available from n8n 1.0.

6. 06

   Enable explicit garbage collection for heavy workflows

   For workflows that process large files or long loops, you can help V8 release memory more aggressively:

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

   This exposes global.gc() — n8n can call it between workflow steps. Combine it with EXECUTIONS_DATA_SAVE_ON_SUCCESS=none if you do not need the execution history: retained execution data often represents 30–50% of the heap.

7. 07

   Monitor the heap after the fix

   Enable n8n metrics to observe heap evolution without manual intervention:

   N8N_METRICS=true
   N8N_METRICS_PREFIX=n8n_

   The /metrics endpoint (port 5678) then exposes nodejs_heap_size_used_bytes and nodejs_heap_size_total_bytes, compatible with Prometheus. A basic Grafana dashboard on these two metrics will alert you well before the next crash.

Post-fix configuration: useful environment variables

Troubleshooting — real errors and their causes

Resources and next steps