[{"data":1,"prerenderedAt":151},["ShallowReactive",2],{"seo-verification":3,"blog-n8n-out-of-memory-fix-vps-production-en":6},{"google":4,"bing":5},"EycwPY2XMyTkVzas3n1ygeNJFGAH513qrMjfDljzsMQ","",{"key":7,"data":8},"blog-n8n-out-of-memory-fix-vps-production-en",{"id":9,"slug":10,"slugs":11,"title":15,"excerpt":16,"readTime":17,"views":18,"isPinned":19,"publishedAt":20,"updatedAt":21,"category":22,"categories":27,"featuredImage":29,"bgImage":30,"posterImage":31,"relatedSolution":32,"intro":35,"sections":36,"ctaTitle":92,"ctaBody":93,"ctaButton":94,"ctaUrl":95,"relatedPosts":96},420,"n8n-out-of-memory-fix-vps-production",{"fr":12,"en":10,"ar":13,"es":14},"n8n-erreurs-memoire-oom-production-vps","n8n-إصلاح-أخطاء-الذاكرة-heap-vps","n8n-errores-memoria-oom-correccion-vps","n8n out of memory: diagnosis and fix on a VPS","FATAL ERROR heap out of memory on n8n: find the root cause (V8 heap cap, webhook mode, unseparated workers) and fix it without migrating.",9,0,false,"2026-10-07T00:00:00+00:00","2026-10-07T23:07:24+00:00",{"id":23,"name":24,"slug":25,"color":26,"icon":25},2,"Automation","automatisation","bg-brand-action\u002F10 text-brand-action",[28],{"id":23,"name":24,"slug":25,"color":26,"icon":25},null,"\u002Fblog\u002Fcovers\u002Fbg.svg","\u002Fblog\u002Fcovers\u002Fn8n-erreurs-memoire-oom-production-vps-poster.svg",{"categorySlug":33,"appSlug":34},"automation-workflows","n8n","The message `FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory` kills n8n with no prior warning. Many teams add more RAM and see no change — because the V8 heap cap is independent of the server's physical memory and must be set explicitly. This article covers the three real causes of the OOM crash, the environment variable that fixes each one, and the worker\u002Fwebhook separation that prevents recurrence.",[37,41,51,54,79,83,86,89],{"type":38,"title":39,"body":40},"h2","Why n8n crashes on memory, and not for the reason you think","V8, the JavaScript engine bundled with Node.js, has a heap cap that is independent of physical RAM. By default it ranges from 512 MB to 1.5 GB depending on the Node version and platform — on a 4 GB or 8 GB VPS, the machine is not out of memory, but the V8 process is. Adding more RAM to the server changes nothing without `NODE_OPTIONS=--max-old-space-size`.\n\nA second common cause: in `main` mode (the default), n8n executes workflows in the same process that serves webhooks and the API. A data-heavy workflow — CSV transformation, aggregation of thousands of rows, looping GPT calls — monopolises the heap during execution. If several pile up, the V8 cap is hit and the process is killed.\n\nA third, subtler cause: jobs accumulate in memory when queue mode is enabled without dedicated workers. The queue (Redis or BullMQ) offloads executions from the main process, but if no worker actually consumes the jobs, they pile up, callbacks stay pending and the heap grows.",{"type":42,"title":43,"items":44},"ul","Signals that confirm an n8n OOM crash",[45,46,47,48,49,50],"**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 \u003Cpid> (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",{"type":38,"title":52,"body":53},"Prerequisites before intervening","These steps assume n8n is already running on your VPS via Docker Compose. If that is not the case, the `installer-n8n-vps` article covers the complete deployment from scratch — come back here once the instance is up.\n\nWhat you need to apply the fixes:\n\n- **Root SSH access** to the VPS and an editable `docker-compose.yml`\n- **Available memory**: a V8 cap of 4,096 MB (`--max-old-space-size=4096`) requires at least 6 GB of RAM on the VPS to leave headroom for the operating system, workers and Redis\n- **Redis** already deployed if you switch to queue mode — `redis:7-alpine` is sufficient for single-VPS use\n- **n8n version** 1.0 or higher: main\u002Fworker separation has been available since version 0.214 but is only stable in production from 1.0 onwards\n- **Database backup** before any Compose modification — credentials and execution tables are not part of the Docker image",{"type":55,"title":56,"steps":57},"steps","Fixing OOM: from diagnosis to stable configuration",[58,61,64,67,70,73,76],{"title":59,"body":60},"Confirm the cause in logs","Read the last 200 lines of the container at the time of the crash:\n\n```bash\ndocker logs n8n --tail 200 2>&1 | grep -E \"FATAL|heap|OOM|Killed\"\n```\n\nIf 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.",{"title":62,"body":63},"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:\n\n- VPS **4 GB**: `--max-old-space-size=2048`\n- VPS **8 GB**: `--max-old-space-size=4096`\n- VPS **16 GB**: `--max-old-space-size=8192`\n\nRule: reserve roughly half the RAM available after the operating system and ancillary services (Redis, proxy). Do not exceed 70% of total RAM.\n\n```bash\nservices:\n  n8n:\n    image: n8nio\u002Fn8n:latest\n    environment:\n      - NODE_OPTIONS=--max-old-space-size=4096\n      # ... other variables\n```",{"title":65,"body":66},"Verify the value is actually read","After `docker compose up -d`, verify Node reads the cap:\n\n```bash\ndocker exec n8n node -e \"const v8=require('v8'); console.log(v8.getHeapStatistics().heap_size_limit \u002F 1024 \u002F 1024, 'MB')\"\n```\n\nThe 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.",{"title":68,"body":69},"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:\n\n```yaml\nservices:\n  redis:\n    image: redis:7-alpine\n    restart: unless-stopped\n    volumes:\n      - redis_data:\u002Fdata\n\n  n8n:\n    image: n8nio\u002Fn8n:latest\n    environment:\n      - NODE_OPTIONS=--max-old-space-size=2048\n      - EXECUTIONS_MODE=queue\n      - QUEUE_BULL_REDIS_HOST=redis\n      - QUEUE_BULL_REDIS_PORT=6379\n    depends_on:\n      - redis\n    ports:\n      - \"5678:5678\"\n\n  n8n-worker:\n    image: n8nio\u002Fn8n:latest\n    command: worker\n    environment:\n      - NODE_OPTIONS=--max-old-space-size=4096\n      - EXECUTIONS_MODE=queue\n      - QUEUE_BULL_REDIS_HOST=redis\n      - QUEUE_BULL_REDIS_PORT=6379\n    depends_on:\n      - redis\n    scale: 2\n\nvolumes:\n  redis_data:\n```\n\nThe `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.",{"title":71,"body":72},"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:\n\n```yaml\n  n8n-webhook:\n    image: n8nio\u002Fn8n:latest\n    command: webhook\n    environment:\n      - NODE_OPTIONS=--max-old-space-size=1024\n      - EXECUTIONS_MODE=queue\n      - QUEUE_BULL_REDIS_HOST=redis\n      - QUEUE_BULL_REDIS_PORT=6379\n      - N8N_DISABLE_UI=true\n    depends_on:\n      - redis\n    ports:\n      - \"5679:5678\"\n```\n\nThen configure your reverse proxy to route `\u002Fwebhook\u002F` to port 5679 and the rest to port 5678 of the main process. Webhook mode is available from n8n 1.0.",{"title":74,"body":75},"Enable explicit garbage collection for heavy workflows","For workflows that process large files or long loops, you can help V8 release memory more aggressively:\n\n```bash\nNODE_OPTIONS=\"--max-old-space-size=4096 --expose-gc\"\n```\n\nThis 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.",{"title":77,"body":78},"Monitor the heap after the fix","Enable n8n metrics to observe heap evolution without manual intervention:\n\n```bash\nN8N_METRICS=true\nN8N_METRICS_PREFIX=n8n_\n```\n\nThe `\u002Fmetrics` 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.",{"type":80,"title":81,"body":82},"tip","Limit execution payload size","The `EXECUTIONS_DATA_MAX_SIZE` parameter (in bytes, default: no limit) cuts an execution before it can overflow the heap. Recommended value for general-purpose instances: `16777216` (16 MB). A workflow exceeding this threshold fails cleanly instead of killing the entire process. Combine it with `EXECUTIONS_DATA_PRUNE=true` and `EXECUTIONS_DATA_MAX_AGE=168` (one week) to avoid accumulation of past execution data.",{"type":38,"title":84,"body":85},"Post-fix configuration: useful environment variables","Once OOM is resolved, these variables consolidate instance stability:\n\n- `N8N_DEFAULT_BINARY_DATA_MODE=filesystem` — stores binary files on disk rather than in memory; essential for workflows handling large CSV or PDF files\n- `OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=true` — manual executions (triggered from the editor) also go through workers, avoiding heap pressure on the main process during testing\n- `N8N_RUNNERS_ENABLED=true` and `N8N_RUNNERS_MAX_CONCURRENCY=5` — enables the experimental task runner (n8n 1.10+) which isolates each execution in a subprocess, preventing a single workflow from consuming all available heap\n- `DB_POSTGRESDB_*` — migrating from SQLite to PostgreSQL on high-volume instances: SQLite serialises all reads\u002Fwrites and can block workers, amplifying memory pressure",{"type":38,"title":87,"body":88},"Troubleshooting — real errors and their causes","**`FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory`**\nDirect cause: the V8 heap has reached its cap. Solution: add `NODE_OPTIONS=--max-old-space-size=\u003Cn>` in the container environment variables, with a value calibrated to available RAM (see step 2).\n\n**`Killed` in logs, without a Node message**\nCause: the Linux kernel OOM killer terminated the process before V8 could emit its message. Occurs when physical memory is actually exhausted — different from a pure V8 crash. Check with `dmesg | grep -i oom`. Reduce `--max-old-space-size` or add RAM, and enable `EXECUTIONS_DATA_SAVE_ON_SUCCESS=none` to lighten the footprint.\n\n**Workers do not consume jobs despite `EXECUTIONS_MODE=queue`**\nCommon cause: `DB_TYPE` and database variables are not passed to workers. Each Compose service must have its own connection variables — the worker does not inherit the main process configuration. Check with `docker exec n8n-worker env | grep DB_`.\n\n**Heap climbs after each run and does not come back down**\nCause: a closure holds a reference to a large array between executions. Enable `--expose-gc` in `NODE_OPTIONS` and add `EXECUTIONS_DATA_SAVE_ON_SUCCESS=none`. If the behaviour persists, switch to task runner mode (`N8N_RUNNERS_ENABLED=true`), which isolates each workflow.\n\n**`Error: Redis connection failed` after switching to queue mode**\nCause: `QUEUE_BULL_REDIS_HOST` points to `localhost` instead of the Docker service name. In a Compose network, the main process and workers reach Redis by its service name (`redis` in the example above), not `127.0.0.1`.",{"type":38,"title":90,"body":91},"Resources and next steps","The official n8n documentation on memory errors (\u003Ca href=\"https:\u002F\u002Fdocs.n8n.io\u002Fhosting\u002Fscaling\u002Fmemory-errors\u002F\">docs.n8n.io\u002Fhosting\u002Fscaling\u002Fmemory-errors\u003C\u002Fa>) details recommended `--max-old-space-size` values based on available RAM and lists scaling parameters. The GitHub issue \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fn8n-io\u002Fn8n\u002Fissues\u002F17461\">n8n-io\u002Fn8n#17461\u003C\u002Fa> (OOM in production, opened March 2026, 80+ comments) documents real-world cases — including the correlation between CSV processing workflows and heap crashes — and configurations that have stabilised instances similar to yours.\n\nIf you manage multiple n8n instances for different clients, the main\u002Fworker separation described here is also the foundation of a multi-tenant architecture: each client can have their own worker pool with an independent V8 cap, without a heavy workflow from one account impacting others.","Deploy n8n on a dedicated VPS","A VPS with root access, dedicated IPv4 and choice of OS to host your n8n instance in queue mode, without workflow or webhook limits.","See VPS templates","\u002Fmarketplace\u002Fautomation-workflows\u002Fn8n",[97,114,135],{"id":98,"slug":99,"slugs":100,"title":104,"excerpt":105,"readTime":106,"views":23,"isPinned":19,"publishedAt":107,"updatedAt":108,"category":109,"categories":110,"featuredImage":29,"bgImage":30,"posterImage":112,"relatedSolution":113},3,"install-n8n-on-vps-with-docker-complete-2026-guide",{"fr":101,"en":99,"ar":102,"es":103},"installer-n8n-vps","تثبيت-n8n-على-vps-مع-docker-دليل-شامل-2026","instalar-n8n-en-vps-con-docker","Install n8n on VPS with Docker: complete 2026 guide","Deploy n8n on VPS with Docker, reverse proxy and HTTPS. Covers V8 crash, 502 nginx, npm migration and execution security (GHSA-vrv8-j27g-g7cr advisory, August 2026).",16,"2026-06-05T00:00:00+00:00","2026-09-23T15:23:17+00:00",{"id":23,"name":24,"slug":25,"color":26,"icon":25},[111],{"id":23,"name":24,"slug":25,"color":26,"icon":25},"\u002Fblog\u002Fcovers\u002Finstaller-n8n-vps-poster.svg",{"categorySlug":33,"appSlug":34},{"id":115,"slug":116,"slugs":117,"title":121,"excerpt":122,"readTime":123,"views":18,"isPinned":19,"publishedAt":124,"updatedAt":125,"category":126,"categories":131,"featuredImage":29,"bgImage":30,"posterImage":133,"relatedSolution":134},410,"n8n-sustainable-use-license-guide-agencies",{"fr":118,"en":116,"ar":119,"es":120},"n8n-sustainable-use-licence-fair-code-agences","n8n-ترخيص-استخدام-مستدام-دليل-وكالات","n8n-licencia-uso-sostenible-guia-agencias","n8n Sustainable Use License: What Agencies Must Know","The n8n SUL allows internal use but prohibits providing n8n as a service to clients without a commercial agreement. What this means for agencies.",8,"2026-10-04T00:00:00+00:00","2026-10-05T14:05:27+00:00",{"id":127,"name":128,"slug":129,"color":130,"icon":129},10,"Compliance & Regulation","conformite","bg-amber-500\u002F10 text-amber-400",[132],{"id":127,"name":128,"slug":129,"color":130,"icon":129},"\u002Fblog\u002Fcovers\u002Fn8n-sustainable-use-licence-fair-code-agences-poster.svg",{"categorySlug":33,"appSlug":34},{"id":136,"slug":137,"slugs":138,"title":142,"excerpt":143,"readTime":17,"views":18,"isPinned":19,"publishedAt":144,"updatedAt":21,"category":145,"categories":146,"featuredImage":29,"bgImage":30,"posterImage":148,"relatedSolution":149},418,"activepieces-the-mit-n8n-alternative-for-agencies-and-ai-agents",{"fr":139,"en":137,"ar":140,"es":141},"activepieces-alternative-n8n-self-hosted-mcp-agents-ia","activepieces-بديل-n8n-mit-للوكالات-وعملاء-الذكاء-الاصطناعي","activepieces-la-alternativa-mit-a-n8n-para-agencias-y-agentes-ia","Activepieces: the MIT n8n alternative for agencies and AI agents","n8n restricts commercial use with its Sustainable Use License. Activepieces is MIT, self-hosted, and connects your Claude or GPT-4o agents via native MCP.","2026-10-06T00:00:00+00:00",{"id":23,"name":24,"slug":25,"color":26,"icon":25},[147],{"id":23,"name":24,"slug":25,"color":26,"icon":25},"\u002Fblog\u002Fcovers\u002Factivepieces-alternative-n8n-self-hosted-mcp-agents-ia-poster.svg",{"categorySlug":33,"appSlug":150},"activepieces",1791414822324]