Fix: n8n JavaScript heap out of memory
n8n holds every item of an execution in memory, so big runs crash the whole process. Raise the heap for headroom, then fix the structure: binary data on disk and work split into sub-workflows.
Symptoms — what you're seeing
- The container log shows
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memoryand n8n restarts - The editor says "Execution stopped at this node — n8n may have run out of memory while running this execution"
- It happens on big runs: thousands of rows, a large CSV or PDF, a paginated API pull, or a loop over many items
- Small test runs work; the same workflow on real data crashes
- Other workflows on the instance fail at the same moment, because the whole process died
Why this happens
n8n runs each execution inside one Node.js process and keeps every item of every node in memory until the execution ends. A workflow that pulls 50,000 contacts, transforms them, then writes them out holds all three copies at once. Node.js also caps its heap below what the server has, often 2–4 GB depending on version and container limits. Cross that line and the whole process dies, not just the workflow.
The usual culprits, roughly in order:
- Everything in one execution. One run fetches every page of an API and processes all of it. The fix is structural: smaller executions, not a bigger heap.
- Binary data in memory. Files (PDFs, images, CSVs) held in memory instead of on disk. Ten 50 MB files is half a gigabyte before you've done anything.
- Code nodes that build huge arrays in "Run Once for All Items" mode, or that copy items with spread operators in a loop.
- Saving huge execution data. Writing every successful execution's full data to the database, and opening large executions in the editor, both cost memory.
The fix, step by step
- Give Node.js a heap that matches the container. This buys headroom while you fix the structure. Keep it about 75% of the container's memory so the OS and n8n itself still fit:
# docker-compose.yml services: n8n: environment: - NODE_OPTIONS=--max-old-space-size=3072 # MB deploy: resources: limits: memory: 4gRaising the flag without raising the container limit just moves the crash: the kernel kills the container instead. - Move binary data to disk. Set
N8N_DEFAULT_BINARY_DATA_MODE=filesystem(older versions default to memory) and make sure the n8n data volume has room. Files then live on disk and only a reference sits in memory. - Split the work into sub-executions. This is the real fix. Fetch in pages, and hand each page to a sub-workflow through the Execute Workflow node. Memory used by a sub-workflow is released when it finishes, so the parent only ever holds one page:
Schedule Trigger → HTTP Request (page N, limit 500) → Execute Workflow: "Process batch" ← transform + write 500 items, then exits → IF hasMore → loop back with page N+1
Inside the parent, Loop Over Items with a batch size of 100–500 does the same for item lists you already have. Return only a small summary (counts, IDs) from the sub-workflow, not the processed items. - Slim down Code nodes. Use "Run Once for Each Item" where you can, return only the fields downstream nodes need, and drop raw API payloads once you've extracted from them. A Set node with "Keep Only Set" after a big HTTP response often halves memory use.
- Stop saving what you don't need. For high-volume workflows, set "Save successful production executions" to off in workflow settings, and prune globally:
EXECUTIONS_DATA_PRUNE=true EXECUTIONS_DATA_MAX_AGE=168 # hours EXECUTIONS_DATA_SAVE_MANUAL_EXECUTIONS=false
Don't open a 200 MB execution in the editor to debug it. The browser and the server both pay for it. - Isolate heavy work with queue mode. If you self-host with Redis, run heavy batch workflows on their own workers with a low concurrency (
--concurrency=2). A crash then takes down one worker, not your webhooks and every other client's automations.
Common variations
- "It only crashes on the full dataset" — memory grows with item count. Split into sub-workflows; a bigger heap only moves the ceiling.
- "It crashes reading a large CSV or PDF" — binary data is in memory mode. Switch to filesystem mode and split the file before processing.
- "Memory keeps climbing across runs until it crashes" — a leak or accumulating static data. Check Code nodes writing to
$getWorkflowStaticData, and restart on a schedule while you track it down. - "Loop Over Items is still slow and heavy" — the loop body holds everything until the end. Move the body into a sub-workflow so each batch is released.
- "n8n Cloud says it ran out of memory" — your plan's memory is fixed. Splitting into sub-workflows and filesystem-friendly batches is the only lever.
When this isn't the issue
- If the execution fails with 429 rather than crashing, you're rate-limited — batching helps, but see n8n OpenAI 429 rate limit.
- If the container keeps restarting with exit code 137 and no heap error, the host or Docker killed it. Raise the container memory limit, not
NODE_OPTIONS. - If runs are green but data goes missing, memory isn't the problem — see n8n data not reaching the output.
The n8n production reliability checklist covers retention, version pinning and splitting critical workflows from heavy ones.
Need this workflow customized or debugged? Book a 30-min scope call →
Stuck configuring this workflow?
I build and fix n8n workflows for agencies and SaaS teams. 30-minute scope call — bring the problem, leave with an estimate.