FATAL ERROR: heap out of memory during a webpack or npm build
FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memoryShort 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.
Fix it fast
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'"2Match what you see, then jump to its fix
- 1
The crash comes late in the build, and the machine had memory freeThe default heap limit is too small for the buildFix - 2
The 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
You set NODE_OPTIONS but the limit shown in the check does not changeAnother flag overrides your settingFix
- 1
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 build3Verify
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
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_OPTIONS2Fix
Lower the value so it fits, or move the build to a bigger runner.
NODE_OPTIONS=--max-old-space-size=1536 npm run build3Verify
Watch the run finish without heavy swapping.
npm run buildConfirmed by nodejs.org
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.json2Fix
Keep one place that sets the flag and remove the others.
node --max-old-space-size=4096 node_modules/webpack/bin/webpack.js3Verify
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
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
Related fixes
Web apps
ChunkLoadError: Loading chunk failed after a Next.js deploy
Missing assets: the client requests JavaScript or CSS files that no longer exist on the server
A browser asked for a JavaScript file that the server no longer has or that another instance never built.
2 causes, each with a fixWeb apps
A React component crashes while destructuring props or state
TypeError: Cannot destructure property 'b' of 'null' as it is null.
JavaScript throws this when the right side of a destructuring pattern is undefined or null.
3 causes, each with a fixWeb 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 fixWeb apps
Sentry: Non-Error promise rejection captured with value in a React app
Non-Error exception (or promise rejection) captured with keys: x, y, z
Sentry raises this event when something that is not an Error object is thrown or used to reject a promise, for example a plain object from an API.
3 causes, each with a fixWeb 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 fixWeb apps
TypeError: undefined is not iterable when destructuring a hook or array
TypeError: object is not iterable (cannot read property Symbol(Symbol.iterator))
Array destructuring, spread, for...of and new Set all need an iterable.
4 causes, each with a fix