Fix "JavaScript heap out of memory" build OOM on Coolify

Error: FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory / Build script returned non-zero exit code: 137 (OOMKilled)

The build ran the server out of RAM and Docker killed the process (exit 137), so no image is produced.

Coolify builds the image on the same server that runs your other apps and databases. Framework production builds (Next.js, Nuxt, large Vite/webpack bundles) peak around 1.5-3 GB, and the heaviest phase is often the server/SSR compile after the client build already succeeded. On a small 1-2 GB VPS with no swap, V8 hits its heap ceiling or the kernel OOM-kills the build (exit 137), made worse when other containers are also holding RAM. Note: setting Node's heap limit equal to the container memory limit makes the OOM killer fire before V8 can recover, so leave headroom.

The fix

  1. Add a swap file so the build has headroom on a small VPS. SSH in as root. (Skip if swap already exists or the box has plenty of free RAM.)

    fallocate -l 2G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile && echo '/swapfile none swap sw 0 0' >> /etc/fstab

  2. Raise Node's heap limit for the build. In Coolify's app Environment Variables, add NODE_OPTIONS=--max-old-space-size=3072 and make sure its "Build Variable" flag is ticked so it applies during the build, not only at runtime (both Build and Runtime are on by default). Keep this value below the container/VPS memory limit so V8 can fail gracefully instead of being OOM-killed.

    NODE_OPTIONS=--max-old-space-size=3072   # Build Variable = ON

  3. If the box is tiny, stop competing containers during the deploy, or better, offload builds. Coolify supports a dedicated Build Server: in Servers, mark a separate machine as a build server so production RAM isn't touched during builds. Caveat: a server flagged as a build server cannot also deploy apps, and build servers require a connected container registry to push the image to.

  4. If it still OOMs, the build genuinely needs more memory than the VPS has. Temporarily resize to a 4 GB plan, ship the build, confirm it deploys, then resize back down.

    free -h   # confirm available RAM + swap before redeploying

  5. Redeploy.

Verify it worked

The build finishes and pushes an image with no "heap out of memory" or exit 137 in the deploy log; free -h during a build shows swap being used rather than the build dying.

free -h

Related Coolify errors

Have Emsden Studio fix it for you — from A$149

All Coolify deploy errors