n8n memory limit error – fatal: reached heap limit allocation failed

Step by Step Guide to solve n8n memory limit error

 

Quick Diagnosis
Fix the “JavaScript heap out of memory” / “OOM killed” crash when starting n8n

• Node.js: add --max-old-space-size=2048 (or higher) to the NODE_OPTIONS env var or npm script.
• Docker: set a RAM limit (mem_limit in docker‑compose.yml or --memory / --memory-swap on docker run).
• Swap (Linux hosts): enable a swap file ≥ 2 GB and tune vm.swappiness to 10‑20.
• Verify: docker stats (or ps -o %mem) shows < 80 % RAM usage; journalctl -u n8n no longer reports OOM.

---

Who this is for – DevOps engineers, system administrators, and n8n power users who run n8n in production and need a reliable way to eliminate out‑of‑memory crashes. We cover this in detail in the n8n Installation Errors Guide.

---

Why n8n hits the memory ceiling

n8n runs on Node.js, which defaults to a ~1.5 GB V8 heap on 64‑bit systems. Complex workflows, large payloads, or many concurrent executions can quickly exceed this limit, causing the JavaScript heap out of memory error or triggering the Linux OOM‑killer. Raising Node’s heap size and configuring container resources prevents the crash while keeping the service stable.

---

1. Adjust Node.js heap size (npm / plain binary)

If you encounter any database connection error n8n resolve them before continuing with the setup.

When you start n8n locally with npm – add the heap flag to the start script:

{
  "scripts": {
    "start": "NODE_OPTIONS=--max-old-space-size=2048 n8n"
  }
}

When you run n8n as a service or inside Docker – export the variable before launching:

export NODE_OPTIONS=--max-old-space-size=2048
n8n start

Permanent system‑wide setting (Linux) – place the export in a profile script:

# /etc/profile.d/n8n.sh
export NODE_OPTIONS=--max-old-space-size=3072

EEFA note: Setting the heap too high on a low‑memory host can cause the OOM‑killer to act faster. Start with 2048 MB, monitor usage, then increase in 256 MB increments.

---

2. Docker‑specific memory allocation

If you encounter any n8n startup failure error resolve them before continuing with the setup.

2.1 Using docker run

Add the heap flag and RAM limits directly in the run command:

docker run -d \
  --name n8n \
  -e NODE_OPTIONS=--max-old-space-size=2048 \
  --memory=2g \
  n8nio/n8n

If you want the container to use swap (requires host swap), append the swap flag:

docker run -d \
  --name n8n \
  -e NODE_OPTIONS=--max-old-space-size=2048 \
  --memory=2g \
  --memory-swap=3g \
  n8nio/n8n

2.2 Using docker‑compose.yml

Service definition with heap flag:

services:
  n8n:
    image: n8nio/n8n
    environment:
      - NODE_OPTIONS=--max-old-space-size=2048

Resource limits (RAM & reservation):

    deploy:
      resources:
        limits:
          memory: 2g          # hard RAM cap
        reservations:
          memory: 1.5g        # guaranteed RAM
    mem_swappiness: 10       # optional, Docker ≥ 20.10

EEFA warning: mem_swappiness is ignored on Docker Desktop for Windows/macOS; use host‑level swap instead.

---

3. Enabling and tuning swap on the host (Linux)

3.1 Create a 4 GB swap file

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

3.2 Persist swap across reboots

/swapfile none swap sw 0 0

3.3 Tune kernel swappiness

sudo sysctl vm.swappiness=15
echo "vm.swappiness=15" | sudo tee -a /etc/sysctl.conf

EEFA tip: A swappiness of 10‑20 gives a good balance for workflow‑heavy n8n instances; higher values may degrade performance.

---

4. Diagnosing the root cause

Symptom	Log clue	Quick check
FATAL ERROR: Reached heap limit Allocation failed – JavaScript heap out of memory	node:… line in n8n.log	docker exec n8n node -e “console.log(process.memoryUsage())”
Container killed with SIGKILL	docker logs n8n shows oom‑kill	docker inspect –format='{{.State.OOMKilled}}’ n8n → true
Slow startup, high CPU	top shows node at 90 % CPU, RAM < 70 %	May be an infinite loop in a workflow – disable recent workflow and restart.

Step‑by‑step troubleshooting checklist

1. Check logs – docker logs n8n or journalctl -u n8n.
2. Inspect memory usage – docker stats n8n (look at %MEM).
3. Confirm heap size – docker exec n8n node -p "process.env.NODE_OPTIONS".
4. Adjust limits – apply one of the methods above.
5. Restart – docker restart n8n (or systemctl restart n8n).
6. Validate – run a heavy workflow; monitor docker stats for < 80 % RAM.

---

5. Production‑grade best practices

Practice	Why it matters	Implementation
Separate execution workers	Isolates heavy jobs, prevents one workflow from starving others.	Deploy n8n with the worker mode (EXECUTIONS_PROCESS=main) and a dedicated queue (e.g., Redis).
Automatic restarts	Guarantees uptime if OOM still occurs.	Use Docker’s restart: unless-stopped or systemd Restart=on-failure.
Monitoring	Early detection before a crash.	Enable Prometheus metrics (N8N_METRICS=true) and set alerts on process_resident_memory_bytes.
Limit concurrent executions	Controls memory spikes.	Set EXECUTIONS_MAX=5 (environment variable).

---

6. Common pitfalls & how to avoid them

Pitfall	Symptom	Fix
Setting NODE_OPTIONS after the container has started	Heap remains at default 1.5 GB.	Ensure NODE_OPTIONS is defined before the n8n process launches (in Dockerfile ENV or compose environment).
Using --memory-swap without host swap	Container still OOM‑killed.	Enable swap on the host first (see §3).
Over‑allocating RAM on low‑memory VMs	Host becomes unresponsive.	Keep container limit ≤ 80 % of host RAM; monitor with htop.
Mixing --max-old-space-size with --max-semi-space-size	Node crashes with “invalid flag”.	Use only --max-old-space-size; the semi‑space flag is rarely needed.

---

7. Quick reference cheat sheet

Setting	Where	Typical value
NODE_OPTIONS	Env var (Docker, systemd)	–max-old-space-size=2048
Docker RAM limit	docker run --memory or compose deploy.resources.limits.memory	2g
Docker swap limit	docker run --memory-swap	3g
Host swap file	/swapfile	4G
Swappiness	vm.swappiness	15
Max concurrent executions	EXECUTIONS_MAX	5
Restart policy	Docker restart: or systemd Restart=	unless-stopped / on-failure