How to Fix n8n Out of Memory (OOM) Errors When Processing Large Files or CSVs

The Anatomy of an n8n Out of Memory (OOM) Crash

To resolve memory exhaustion permanently, you must understand how n8n and Node.js manage memory under heavy computational load:

• The V8 JavaScript Heap Limit: Node.js runs on Google’s V8 engine, which historically imposes a default maximum old space memory limit of approximately 1.4GB on 64-bit systems. When an n8n node creates hundreds of thousands of JavaScript objects simultaneously, the garbage collector cannot reclaim memory fast enough, triggering a fatal heap panic:

  FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

• The 10x JSON Expansion Multiplier: A 50MB flat CSV file does not consume 50MB of RAM. When the Read Binary Files or Spreadsheet File node parses the file into an n8n item array, each row is converted into an independent JavaScript object with metadata, key strings, and prototype chains. A 50MB CSV routinely balloons to 1.5GB to 2.5GB of RAM!
• Linux Kernel OOM Killer (Exit Code 137): When your Docker container exceeds its allocated cgroup memory limit or the host server runs out of physical RAM and swap space, the Linux kernel invokes oom-killer to protect the operating system, instantly terminating the n8n process with SIGKILL (128 + 9 = 137).

Architectural Overview: Default vs Hardened n8n Configuration

Fix 1: Switch Binary Data Mode to Filesystem Storage

By default, n8n loads all downloaded files, generated PDFs, and CSVs directly into Node.js memory buffers. If your workflow downloads a 150MB file, that entire 150MB is pinned to your RAM.

Instruct n8n to stream binary payloads to disk by setting the following environment variable in your docker-compose.yml:

environment:
  - N8N_DEFAULT_BINARY_DATA_MODE=filesystem
  - N8N_BINARY_DATA_STORAGE_PATH=/data/binary
volumes:
  - n8n_data:/data

This single configuration change immediately drops n8n baseline memory consumption by up to 80% during heavy file transfers.

Fix 2: Expand V8 Heap Limit with NODE_OPTIONS

If your host server has 8GB or 16GB of RAM, n8n will still crash at ~1.4GB unless you explicitly tell Node.js to expand its memory allocation ceiling:

environment:
  # Allocate 4GB (4096MB) of heap space to Node.js
  - NODE_OPTIONS=--max-old-space-size=4096

Rule of Thumb: Set --max-old-space-size to approximately 65% to 75% of your container’s total Docker memory allocation, leaving the remaining memory for the Linux kernel, system buffers, and database drivers.

Fix 3: Implement Loop Over Items (Batch Chunking)

Never push 50,000 items through downstream HTTP Request or database insertion nodes simultaneously. n8n will attempt to execute thousands of simultaneous promises, flooding the event loop and exhausting RAM.

Instead, use the native Loop Over Items (or legacy Split In Batches) node:

1. Set Batch Size: 500 (or 1000 depending on payload width).
2. Execute your transformations, API requests, and database updates inside the loop.
3. At the end of each iteration, n8n releases references to completed item objects, allowing the V8 garbage collector to free memory before pulling the next batch.

Fix 4: Offload Multi-Gigabyte CSV Parsing to DuckDB

For enterprise datasets containing 500,000 to 5,000,000+ rows, processing data inside JavaScript is fundamentally the wrong tool. Instead, use n8n’s Execute Command node to delegate the ETL operation to DuckDB (an in-process, high-performance vectorized SQL analytical engine):

Step 1: Install DuckDB inside your custom n8n container

# In your custom Dockerfile
FROM n8nio/n8n:latest
USER root
RUN apt-get update && apt-get install -y wget unzip     && wget https://github.com/duckdb/duckdb/releases/download/v1.1.0/duckdb_cli-linux-amd64.zip     && unzip duckdb_cli-linux-amd64.zip -d /usr/local/bin/     && rm duckdb_cli-linux-amd64.zip
USER node

Step 2: Execute DuckDB Query in n8n Execute Command Node

Instead of parsing a 500MB CSV in n8n, run a single DuckDB SQL command that reads the CSV from disk, filters high-value records, and outputs a lightweight JSON summary:

duckdb -json -c "
  SELECT 
    country, 
    COUNT(*) as total_orders, 
    SUM(price) as gross_revenue 
  FROM read_csv_auto('/data/binary/massive_sales_export.csv')
  WHERE status = 'Completed'
  GROUP BY country
  ORDER BY gross_revenue DESC
  LIMIT 25;
"

DuckDB processes millions of rows in less than 2 seconds, utilizing vectorized C++ instructions, and passes only the 25 aggregated summary rows into n8n. Memory consumption inside n8n: Less than 15MB!

Fix 5: Production Docker-Compose Configuration Blueprint

Deploy your self-hosted n8n instance with this production-tested docker-compose.yml file incorporating memory reservations, swap buffers, and filesystem binary storage:

version: '3.8'

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    restart: always
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=n8n.yourdomain.com
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - NODE_ENV=production
      - WEBHOOK_URL=https://n8n.yourdomain.com/
      # Memory & Binary Optimization
      - N8N_DEFAULT_BINARY_DATA_MODE=filesystem
      - N8N_BINARY_DATA_STORAGE_PATH=/data/binary
      - NODE_OPTIONS=--max-old-space-size=4096
      # Prune Execution History to prevent DB bloat
      - EXECUTIONS_DATA_PRUNE=true
      - EXECUTIONS_DATA_MAX_AGE=168 # 7 days
      - EXECUTIONS_DATA_PRUNE_MAX_COUNT=10000
      - EXECUTIONS_DATA_SAVE_ON_ERROR=all
      - EXECUTIONS_DATA_SAVE_ON_SUCCESS=none
      - EXECUTIONS_DATA_SAVE_MANUAL_EXECUTIONS=false
    deploy:
      resources:
        limits:
          memory: 6144M
        reservations:
          memory: 2048M
    volumes:
      - n8n_data:/data

volumes:
  n8n_data:

Benchmark: Monolithic JavaScript vs Streaming & DuckDB

Scaling n8n into Multi-Process Queue Mode with Redis

In high-volume environments, running n8n in the default monolithic mode means that a single long-running CSV processing job locks up the entire event loop, delaying real-time webhook responses. The ultimate enterprise solution is n8n Queue Mode:

Queue mode decouples the web interface and webhook ingestion servers from execution workers:

# docker-compose.queue.yml
services:
  n8n-main:
    image: docker.n8n.io/n8nio/n8n:latest
    environment:
      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=redis
      - QUEUE_BULL_REDIS_PORT=6379
      - N8N_DEFAULT_BINARY_DATA_MODE=filesystem
    depends_on:
      - redis
      - postgres

  n8n-worker-1:
    image: docker.n8n.io/n8nio/n8n:latest
    command: worker
    environment:
      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=redis
      - QUEUE_BULL_REDIS_PORT=6379
      - N8N_DEFAULT_BINARY_DATA_MODE=filesystem
      - NODE_OPTIONS=--max-old-space-size=4096
    deploy:
      resources:
        limits:
          memory: 6144M

  redis:
    image: redis:7-alpine
    restart: always

If a worker crashes while processing an abnormally malformed CSV, Redis re-queues or isolates the failed job, and the primary n8n main instance remains 100% online without dropping a single incoming webhook.

Eliminating Memory Leaks in JavaScript Code Nodes

A frequent cause of creeping memory bloat in n8n workflows is anti-patterns inside the Code (JavaScript) Node. Avoid creating massive in-memory array copies using .map() or spread operators [...items]:

// ❌ ANTI-PATTERN: Duplicates the entire dataset in RAM
const transformed = $input.all().map(item => {
  return { json: { ...item.json, processed: true } };
});
return transformed;

// ✅ PRODUCTION OPTIMIZED: Mutates in place or yields lazily
const items = $input.all();
for (let i = 0; i < items.length; i++) {
  items[i].json.processed = true;
}
return items;

Production Readiness Checklist: Zero-Crash n8n Infrastructure

# Enable native Prometheus metrics endpoint in n8n
environment:
  - N8N_METRICS=true
  - N8N_METRICS_PREFIX=n8n_

# Prometheus alert rule for impending heap exhaustion
# alert.rules.yml
groups:
  - name: n8n_alerts
    rules:
      - alert: N8nHighMemoryUsage
        expr: container_memory_usage_bytes{container_label_com_docker_compose_service="n8n"} / container_spec_memory_limit_bytes > 0.85
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "n8n container memory exceeds 85% of cgroup limit"
          description: "Container is at risk of Linux kernel OOM termination. Review active workflows."