How to Fix "n8n Out of Memory" Error (JavaScript Heap Overflow)

⏱️ 17 min read · 📥 Free template + 3 explanatory diagrams

You're watching docker logs n8n and the same red line keeps appearing: FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory. The container restarts, works for an hour, crashes again. Your workflows look fine in the editor — they only die in production.

---

1. How n8n Memory Works (3 Layers)

n8n is a Node.js application, and its memory has three layers. Understanding which layer failed tells you exactly which fix to apply:

The critical relationship: your heap limit must stay comfortably below your container limit. Node needs memory outside the heap too — buffers, external libraries, the HTTP stack. Set the heap at 60–75% of the container's limit. If the heap limit exceeds the container limit, the kernel kills the whole process (error #2) before Node can even throw its own error (#1).

---

2. Diagnose in 60 Seconds: The 4 Signatures

Every "out of memory" report on n8n is one of these four. Find yours, then jump to its fix:

Run these four commands — they confirm which signature you have in under a minute:

# 1. Heap overflow? Look for the FATAL ERROR line
docker logs n8n --tail 200 | grep -i "heap out of memory"

# 2. Killed by the kernel? 137 = OOM killer
docker inspect --format='{{.State.ExitCode}} {{.State.Status}}' n8n

# 3. Kernel confirmed the kill? Check the system log
sudo dmesg | grep -i "out of memory" | tail -5

# 4. Live memory usage right now
docker stats --no-stream n8n
free -hCopy

---

3. Prerequisites

• SSH access to the VPS running n8n (or your Docker host).
• Docker + Docker Compose — the snippets assume the standard stack from our n8n Self-Hosted with Docker installation guide.
• 15 minutes for the quick fix; 1–2 hours if you restructure heavy workflows.

---

4. Fix 1: Raise the Heap (Signature #1)

Node lets you raise the heap limit with --max-old-space-size (in megabytes). n8n accepts it through the standard NODE_OPTIONS environment variable.

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    environment:
      # 4096 MB = 4 GB heap — right for a 6–8 GB VPS
      - NODE_OPTIONS=--max-old-space-size=4096
      # Allow single items bigger than the 16 MB default (optional)
      - N8N_PAYLOAD_SIZE_MAX=64
    # ...rest of your configCopy

docker exec n8n node -e "console.log(Math.round(require('v8').getHeapStatistics().heap_size_limit / 1024 / 1024) + ' MB')"Copy

Heap sizing table (per VPS RAM)

---

5. Fix 2: Docker Limits & Swap (Signature #2 — Exit Code 137)

Exit code 137 means the kernel OOM killer terminated the container: the whole system ran out of memory, not just the heap. Raising NODE_OPTIONS won't help here — and can make it worse. Two fixes:

5.1 Explicit container limits

Limits stop one container from eating the whole server and make OOM behavior predictable:

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    # Hard cap: container is OOM-killed at 4 GB
    mem_limit: 4g
    # Soft hint: Docker tries to keep it around 1 GB
    mem_reservation: 1g
    # ...rest of your config

  # Give the OTHER containers caps too — Postgres and Redis
  # share the same physical RAM:
  postgres:
    image: postgres:16-alpine
    mem_limit: 2g
    mem_reservation: 512mCopy

5.2 Add a 2 GB swap safety net

Swap doesn't fix the root cause, but it buys you time when memory spikes — the OS pages to disk instead of killing processes instantly:

# Create and enable a 2 GB swap file (Ubuntu/Debian)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# Make it permanent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstabCopy

---

6. Fix 3: Fix the Workflow (The Permanent Solution)

Raising the heap postpones the crash. These five patterns stop the growth — a workflow that handles 50 items and 50,000 items with nearly the same memory footprint.

6.1 Use the built-in Split In Batches node

The n8n-native solution for large lists: the Split In Batches node processes items in batches of N within one execution, keeping only the current batch in flight. Drag it right after your trigger, set Batch Size to 100–500, and connect the loop output back to it:

• Batch Size 100 — safe default for heavy nodes (HTTP, AI, Sheets)
• Batch Size 500 — fine for lightweight transformations
• Combine with the Limit node upstream to cap total items per execution

6.2 Manual chunking in a Code node

When you need full control over the batching logic:

// Code node — process items in chunks of 100
const items = $input.all();
const CHUNK = 100;
const results = [];

for (let i = 0; i < items.length; i += CHUNK) {
  const batch = items.slice(i, i + CHUNK);
  // Process the batch — keep ONLY what the next node needs
  results.push(...batch.map(item => ({ json: { id: item.json.id } })));
}

return results.map(r => ({ json: r.json }));Copy

6.3 Split heavy logic into sub-workflows

Independent heavy logic (PDF processing, AI scoring, big API pulls) belongs in a separate workflow called via the Execute Workflow node. The sub-workflow gets its own execution, its own memory window, and — in queue mode — its own worker. If it crashes, the parent receives the error instead of dying with it.

6.4 Stream binaries instead of loading them into memory

Files are the #1 silent memory killer. A 200 MB CSV read as JSON text lands entirely in the heap; the same file streamed as binary barely touches it:

• In the HTTP Request node, set Response Format: File so downloads stream to binary storage.
• In Google Drive / S3 / FTP nodes, use their native file operations instead of converting to base64 text.
• Never JSON.stringify a binary item inside a Code node — that copies the whole file into the heap.

6.5 Stop carrying data you don't need

• Use the Limit node to cap items per execution (e.g., 1,000).
• Use Remove Duplicates early — don't let 8,000 duplicates flow through 12 nodes.
• In Code nodes, return only the fields the next node needs (see the snippet above — we kept id, dropped everything else).
• Never accumulate arrays across loop iterations — write to the destination inside the loop instead.
• Clear large values after use: delete item.json.hugeField.

---

7. Fix 4: Queue Mode — Isolate the Crash

When a memory-hungry execution is unavoidable (huge reports, long AI agent runs), the right architecture is queue mode: executions run on separate worker containers, each with its own heap and memory limit. A crash kills one worker — the UI, webhooks, and other workers keep running.

services:
  n8n-worker:
    image: docker.n8n.io/n8nio/n8n
    command: worker
    environment:
      # Per-worker heap — size it like the main process
      - NODE_OPTIONS=--max-old-space-size=4096
      - EXECUTIONS_MODE=queue
      # Parallel jobs per worker — lower this for memory-heavy workflows
      - QUEUE_WORKER_CONCURRENCY=5
    mem_limit: 5g
    # ...Redis + Postgres config per our queue mode guideCopy

---

8. Fix 5: Redis OOM (Signature #3 — Queue Mode Only)

If Redis hits its memory cap in queue mode, it rejects writes and jobs start failing or vanishing. Cap it cleanly with an LRU eviction policy instead of letting it crash:

services:
  redis:
    image: redis:7-alpine
    command: ['redis-server', '--appendonly', 'yes', '--maxmemory', '2gb', '--maxmemory-policy', 'allkeys-lru']
    volumes:
      - redis_data:/dataCopy

Also limit how much history Redis keeps — completed-job metadata grows forever by default:

environment:
  # Keep only the last 1000 completed jobs' metadata
  - QUEUE_BULL_JOB_OPTIONS_REMOVE_ON_COMPLETE=1000Copy

---

9. Find Which Node Eats Your Memory

Nobody tells you how to find the culprit node. Here's the 3-step method we use:

// Temporary memory probe — place after a suspect node, then delete
const mem = process.memoryUsage();
return [{
  json: {
    heapUsedMB: Math.round(mem.heapUsed / 1024 / 1024),
    rssMB: Math.round(mem.rss / 1024 / 1024),
    items: $input.all().length
  }
}];Copy

---

10. Production Tuning: Binary Mode, Concurrency & Pruning

Three switches that prevent memory problems before they start. None of the competitor articles on this error mention any of them:

10.1 Store binary data on disk, not in memory

By default, n8n keeps binary data (files, images, PDFs) in its database — which means every file your workflow touches gets loaded into the process. The filesystem mode writes files to disk instead:

environment:
  # Files land on disk instead of the process memory/database
  - N8N_DEFAULT_BINARY_DATA_MODE=filesystem
  # Cap single items (default 16 MB) and webhook file uploads (default 200 MB)
  - N8N_PAYLOAD_SIZE_MAX=64
  - N8N_FORMDATA_FILE_SIZE_MAX=256Copy

10.2 Cap concurrent executions

Memory = concurrency × footprint per execution. By default n8n runs unlimited production executions in parallel. Ten heavy executions at once on a 2 GB VPS is a guaranteed OOM — no heap setting saves you from arithmetic:

environment:
  # Max simultaneous production executions (default: unlimited)
  - N8N_CONCURRENCY_PRODUCTION_LIMIT=5Copy

10.3 Prune execution data before the database eats your RAM

n8n stores the full data of every execution forever unless you prune it. The executions table grows without bound: the UI slows down, history queries lag, and Postgres consumes more and more RAM — then users report "n8n is slow" without ever seeing a memory error:

environment:
  # Auto-delete old execution data (default: off)
  - EXECUTIONS_DATA_PRUNE=true
  # Keep 7 days of history (default: 336 hours = 14 days)
  - EXECUTIONS_DATA_MAX_AGE=168
  # Hard cap on stored executions
  - EXECUTIONS_DATA_PRUNE_MAX_COUNT=50000
  # Don't store data for successful runs — failures only
  - EXECUTIONS_DATA_SAVE_ON_SUCCESS=none
  - EXECUTIONS_DATA_SAVE_ON_ERROR=allCopy

10.4 Quick math: will this workflow fit in the heap?

Estimate before you run — one probe with real data tells you if chunking is needed:

// Estimation probe — run once with real input data, then delete
const items = $input.all();
const bytesPerItem = JSON.stringify(items[0]?.json || {}).length;
const estPayloadMB = Math.round((bytesPerItem * items.length) / 1024 / 1024);

return [{ json: { items: items.length, bytesPerItem, estPayloadMB } }];Copy

Rule of thumb: if estPayloadMB is more than ~10% of your heap (e.g., 100 MB on a 1 GB heap), chunk it — every downstream node keeps its own working copy, so the real footprint is several times your estimate. If the payload is huge but each item is tiny, use Split In Batches; if each item is huge, that's a streaming problem (section 6.4).

---

11. The 8 Most Common Errors & Fixes

---

12. Free Template: The Memory Watchdog

Every fix above is reactive — you find out after the crash. This watchdog is proactive: it probes n8n's real memory every 5 minutes and sends a Telegram alert before you hit the danger zone. Import the JSON below, set your chat ID, and adjust the threshold to ~60% of your container limit. Here is exactly what it does:

{
  "name": "n8n Memory Watchdog",
  "nodes": [
    {
      "parameters": {
        "rule": {
          "interval": [
            {
              "field": "minutes",
              "minutesInterval": 5
            }
          ]
        }
      },
      "id": "schedule",
      "name": "Every 5 Minutes",
      "type": "n8n-nodes-base.scheduleTrigger",
      "typeVersion": 1.2,
      "position": [250, 300]
    },
    {
      "parameters": {
        "jsCode": "const mem = process.memoryUsage();\nconst heapMB = Math.round(mem.heapUsed / 1024 / 1024);\nconst rssMB = Math.round(mem.rss / 1024 / 1024);\nconst heapLimitMB = Math.round(mem.heapTotal / 1024 / 1024);\nconst thresholdMB = 900;\nconst now = Date.now();\nconst lastAlert = $workflow.staticData.lastAlert || 0;\nconst alert = heapMB > thresholdMB;\nconst notify = alert && (now - lastAlert > 900000);\nif (notify) { $workflow.staticData.lastAlert = now; }\nreturn [{ json: { heapMB, rssMB, heapLimitMB, thresholdMB, alert, notify, timestamp: new Date().toISOString() } }];"
      },
      "id": "probe",
      "name": "Probe Memory",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [450, 300]
    },
    {
      "parameters": {
        "conditions": {
          "options": {
            "caseSensitive": true,
            "leftValue": "",
            "typeValidation": "strict"
          },
          "conditions": [
            {
              "id": "c1",
              "leftValue": "={{ $json.notify }}",
              "rightValue": true,
              "operator": {
                "type": "boolean",
                "operation": "equals"
              }
            }
          ],
          "combinator": "and"
        }
      },
      "id": "if-alert",
      "name": "Notify?",
      "type": "n8n-nodes-base.if",
      "typeVersion": 2,
      "position": [650, 300]
    },
    {
      "parameters": {
        "chatId": "YOUR_TELEGRAM_CHAT_ID",
        "text": "=🧠 n8n MEMORY ALERT\n\nHeap used: {{ $json.heapMB }} MB\nHeap limit: {{ $json.heapLimitMB }} MB\nRSS: {{ $json.rssMB }} MB\nThreshold: {{ $json.thresholdMB }} MB\nTime: {{ $json.timestamp }}"
      },
      "id": "telegram",
      "name": "Telegram Alert",
      "type": "n8n-nodes-base.telegram",
      "typeVersion": 1.2,
      "position": [850, 200],
      "credentials": {
        "telegramApi": {
          "id": "YOUR_TELEGRAM_CREDENTIAL_ID"
        }
      }
    },
    {
      "parameters": {},
      "id": "noop-ok",
      "name": "Memory OK",
      "type": "n8n-nodes-base.noOp",
      "typeVersion": 1,
      "position": [850, 400]
    }
  ],
  "connections": {
    "Every 5 Minutes": {
      "main": [
        [
          {
            "node": "Probe Memory",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Probe Memory": {
      "main": [
        [
          {
            "node": "Notify?",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Notify?": {
      "main": [
        [
          {
            "node": "Telegram Alert",
            "type": "main",
            "index": 0
          }
        ],
        [
          {
            "node": "Memory OK",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "active": false,
  "settings": {
    "executionOrder": "v1",
    "saveManualExecutions": true
  }
}Copy

• Threshold: thresholdMB = 900 in the Probe node. Set it to ~60% of your container limit (e.g., 2400 for a 4 GB container).
• Cooldown: alerts at most once per 15 minutes — no spam during a bad hour.
• Queue mode note: in queue mode this workflow runs on whatever worker picks it up, so it reports that worker's memory — run it on your busiest instance.
• Want more channels? Duplicate the Telegram node for Slack or email — the logic is channel-agnostic. More ready-to-import blueprints live in our n8n Workflow Templates Library.

---

13. Prevention Checklist

• ✅ NODE_OPTIONS=--max-old-space-size sized to 60–75% of container memory
• ✅ Explicit mem_limit on n8n, Postgres, and Redis containers
• ✅ A small (2 GB) swap file as a safety net
• ✅ Split In Batches on every workflow touching large lists
• ✅ Heavy logic isolated in sub-workflows (Execute Workflow node)
• ✅ Files streamed as binary, never stringified in Code nodes
• ✅ Limit nodes capping items per execution
• ✅ Queue mode workers for long-running executions, with sane concurrency
• ✅ The Memory Watchdog running and alerting before the danger zone
• ✅ Error Trigger workflow notifying on every crash (see the Error Handling guide)
• ✅ N8N_DEFAULT_BINARY_DATA_MODE=filesystem for file-heavy workflows
• ✅ N8N_CONCURRENCY_PRODUCTION_LIMIT sized to your RAM
• ✅ Execution data pruning enabled (EXECUTIONS_DATA_PRUNE=true)

---

14. Frequently Asked Questions

---

Sources & References

• Node.js Documentation — --max-old-space-size
• n8n Documentation — General environment variables
• n8n Documentation — Executions environment variables
• n8n Documentation — Queue mode
• Docker Documentation — Compose service configuration (mem_limit)

Explore More Guides