Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

FATAL ERROR: heap out of memory during a webpack or npm build

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

Short answer

The build process hit V8's old-space limit and stopped. Raise the limit with --max-old-space-size, in MiB, and pass it through NODE_OPTIONS so tools that start child processes get it too. Do not set it above the memory the machine really has, or the system will swap and slow down.

  • Applies to Node.js 22, Node.js 24, webpack 5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out how much memory the machine has, so you can choose a limit that fits.

    node -p "Math.round(require('os').totalmem() / 1048576) + ' MiB total'"
  2. 2Match what you see, then jump to its fix

    1. 1The crash comes late in the build, and the machine had memory freeThe default heap limit is too small for the buildFix
    2. 2The build gets very slow, the disk is busy, or the process is killed in a small container or CI runnerThe limit is larger than the machine can giveFix
    3. 3You set NODE_OPTIONS but the limit shown in the check does not changeAnother flag overrides your settingFix

What does the error look like?

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

Cause 1 of 3

The default heap limit is too small for the build

1Check

Read the current limit in MiB.

node -p "Math.round(require('v8').getHeapStatistics().heap_size_limit / 1048576) + ' MiB'"

2Fix

Set a higher limit for the build command. The Node.js docs list --max-old-space-size as allowed in NODE_OPTIONS.

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

3Verify

Run the build again. If it finishes, make the setting permanent in the CI or script that runs it.

# package.json
"build": "NODE_OPTIONS=--max-old-space-size=4096 webpack --mode production"

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 3

The limit is larger than the machine can give

1Check

Compare your value with the memory shown in the first step. The Node.js docs advise leaving room for other work, and give 1536 for a 2 GiB machine.

echo $NODE_OPTIONS

2Fix

Lower the value so it fits, or move the build to a bigger runner.

NODE_OPTIONS=--max-old-space-size=1536 npm run build

3Verify

Watch the run finish without heavy swapping.

npm run build

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 3

Another flag overrides your setting

1Check

Command-line options take precedence over NODE_OPTIONS, and when a single-value option is repeated the last one wins. Look at the full command.

grep -n "max-old-space-size" package.json

2Fix

Keep one place that sets the flag and remove the others.

node --max-old-space-size=4096 node_modules/webpack/bin/webpack.js

3Verify

Print the limit inside the same command and confirm it.

node --max-old-space-size=4096 -p "require('v8').getHeapStatistics().heap_size_limit"

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Set the limit in the script or CI file, not on one person's shell.
  • Size it to the runner's real memory, with room left for the system.
  • Watch build memory when you add large dependencies.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

Jest fails to parse a React Native or Expo dependency

Jest failed to parse a file. This happens e.g. when your code or its dependencies use non-standard JavaScript syntax

Jest does not run Babel on node_modules by default, and many React Native packages ship untranspiled source.

3 causes, each with a fix

Web apps

TypeScript says a JavaScript module implicitly has an any type

Could not find a declaration file for module 'react-materialize'. 'path/to/module-name.js' implicitly has an 'any' type.

TypeScript found the JavaScript file but no types for it, and noImplicitAny turns that into an error.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.