Fixing 'JavaScript heap out of memory' in Node.js on macOS

Why your build is crashingYou are running npm run build, the fans on your MacBook start spinning, and then everything freezes. Instead of a successful bundle, your terminal spits out a massive crash log ending in a memory allocation error. This isn't a bug in your code. It is a resource limit issue.

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

Modern frontend frameworks like Next.js or heavy Angular apps are resource-intensive. By default, Node.js (v12 and later) usually limits itself to about 2GB of memory on 64-bit systems. When Webpack or Vite tries to traverse a dependency tree with 10,000+ files, it hits that 2GB ceiling and dies.

The Quick Fix: Temporary SessionIf you need to push a hotfix right now, don't mess with config files. You can override the limit for your current terminal tab. This command bumps the limit to 4GB, which is enough for 95% of enterprise-level builds.

export NODE_OPTIONS="--max-old-space-size=4096"npm run build

If your project is massive—think hundreds of pages and heavy source maps—bump that number to 8192. Just ensure your Mac has at least 16GB of physical RAM before doing so.

The System-Wide Fix (zsh)Most macOS users run zsh. You can make this memory boost permanent so you never see this error again during local development. This approach is great if you work on multiple large repositories.

• Open your zsh configuration in the editor:nano ~/.zshrc- Paste this line at the bottom:export NODE_OPTIONS="--max-old-space-size=4096"- Save and exit (Press Ctrl+O, Enter, then Ctrl+X).- Apply the changes immediately:source ~/.zshrc## The Team-Friendly Fix: package.jsonSetting a system-wide variable is convenient, but it doesn't help your teammates. If one person hits a memory limit, everyone will. The best practice is to define the limit directly in your project's package.json. This ensures the build works on CI/CD pipelines and other developer machines. Update your scripts like this:

{
  "scripts": {
    "build": "NODE_OPTIONS=--max-old-space-size=4096 next build",
    "dev": "NODE_OPTIONS=--max-old-space-size=4096 next dev"
  }
}

Using Windows too? Install the cross-env package. Then change your script to cross-env NODE_OPTIONS=--max-old-space-size=4096 next build to keep it platform-agnostic.

Verify the ChangeIt is easy to check if Node.js actually accepted your new settings. You can run a one-line command to see the limit in gigabytes.

node -e 'console.log((require("v8").getHeapStatistics().heap_size_limit / 1024 / 1024 / 1024).toFixed(2) + " GB")'

If the output says 4.00 GB, you are good to go. Your builds should now be stable.

A Warning for Apple Silicon (M1/M2/M3) UsersCheck your Node.js architecture. If you migrated from an Intel Mac, you might be running the x64 version of Node via Rosetta 2. This is a performance killer. Running x64 Node on an M2 chip consumes significantly more memory and runs roughly 20-30% slower.

Run this command:

node -p "process.arch"

If it returns x64, you should reinstall Node.js. Use a manager like nvm or fnm to install the arm64 version. Native binaries handle memory much more efficiently, often solving 'out of memory' errors without needing to bump the heap size at all.