JavaScript heap out of memory during next build: how to fix it
Node's JavaScript heap reached its limit while Next.js was building, and V8 stopped the process. Raise the heap limit with NODE_OPTIONS=--max-old-space-size, staying below the memory the build really has, and cut what the build holds in memory: source maps, type checking during the build, and heavy dependencies.
By Livops team, the people who build and run LivopsUpdated
What the end of the build log shows:
<--- Last few GCs --->
...
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
Older Node versions word the last line FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory. This page explains the limit, lists the fixes from the one that most often works, shows how to reproduce the server’s limit on your machine, and says what Livops does about it.
What does the error mean?
Node runs JavaScript in V8, and V8 keeps objects in a heap with a ceiling. --max-old-space-size sets the size of its old memory section; as use approaches the limit, V8 spends more and more time collecting garbage[1]. When it cannot free enough, it stops the process with this error. next build holds the module graph, compiled chunks, source maps and prerendered pages, so a large app can reach the ceiling during the build even when the running site needs much less.
Note that the heap limit is not the machine’s memory. If the limit is above what the container has, the kernel kills the build first, and the log ends with exit code 137 instead of this message.
Fixes, most effective first
1. Set the heap limit explicitly
Tell Node how much it may use, below the build’s real memory. Node’s docs suggest 1536 MiB on a machine with 2 GiB, to leave room for the rest[1]:
NODE_OPTIONS=--max-old-space-size=3072 npx next build
Or in package.json, so every build uses it:
{
"scripts": {
"build": "NODE_OPTIONS=--max-old-space-size=3072 next build"
}
}
2. Turn off source maps in the build
Generating source maps costs extra memory during the build. Disable them with productionBrowserSourceMaps: false and experimental.serverSourceMaps: false; if it runs out after “Generating static pages”, also enablePrerenderSourceMaps: false[2]:
// next.config.mjs
const nextConfig = {
productionBrowserSourceMaps: false,
enablePrerenderSourceMaps: false,
experimental: { serverSourceMaps: false },
}
export default nextConfig
3. Move type checking out of the build
Type checking can take a lot of memory in large projects. When the build runs out during “Running TypeScript”, Next.js lets you skip that step with typescript.ignoreBuildErrors: true[2], and warns that it can produce faulty deploys[2]. Do it only if tsc --noEmit runs in CI before the deploy.
4. Reduce what the build has to hold
- Remove or replace heavy dependencies; the memory guide lists dependency analysis as the first step[2].
- Next.js builds with Turbopack by default;
--webpackswitches to Webpack[3]. If you build with Webpack,experimental.webpackMemoryOptimizations: truelowers its peak memory at a small cost in build time[2], and the Webpack build worker, on by default without a custom Webpack config, keeps compilation in a separate process[2]. - Thousands of pages prerendered at build time all have to be produced during the build. Prerender the important ones and render the rest on demand.
5. Update Next.js
Some memory problems are bugs that were fixed: Next.js 14.1.3, for one, fixed a memory issue with the Edge runtime[2]. Update before tuning further.
How to confirm the fix locally
Run the build under the same ceiling the server has. next build --experimental-debug-memory-usage prints heap use and garbage collection while it builds, and takes heap snapshots near the limit[2]; it does not work together with the Webpack build worker[2].
NODE_OPTIONS=--max-old-space-size=1536 npx next build --experimental-debug-memory-usage
To also reproduce the container’s memory, so an exit code 137 shows up locally too:
docker run --rm -m 2g -v "$PWD":/app -w /app node:22 \
sh -c "npm ci && NODE_OPTIONS=--max-old-space-size=1536 npx next build"
If it passes there with room to spare, it will pass on a build machine of that size.
On Livops
- The heap limit is set for you. For a framework build (not your own Dockerfile), Livops sets
NODE_OPTIONS=--max-old-space-sizeto three quarters of the build container’s memory, so Node can use the memory the build has instead of guessing low. If you setNODE_OPTIONSin Variables yourself, Livops leaves it alone and yours is used. The first line of the build log states the build’s ceiling:Build server: <region> · <n> cores, <memory>. - A Tip when it still runs out. If the log shows
JavaScript heap out of memory, the deploy fails asbuild_failed, and the log ends with a Tip: line: setNODE_OPTIONSin Variables, turn off source maps in production (productionBrowserSourceMaps: false), and if it still does not fit, write to us for a bigger build. Keep a value you set below the ceiling the log states, or the heap error becomes exit code 137. - Nothing goes down. The previous version keeps running while the build fails. A build that runs past ten minutes is stopped as
timed_out. - The assistant explains, you change it. The button next to the failed build reads the log and explains the failure, and for this one points you to the project’s settings. It does not edit your variables or your
next.configon its own. - The running app is sized separately.
next startruns with the service’s memory tier — its type’s default, 512, 1024 or 2048 MiB — which you can set withmemoryinlivops.jsonwhen the project is created, and change later in the settings.
More in the docs: The build ran out of memory.
Questions
What value should max-old-space-size be?
Below the memory the build really has, leaving room for everything that is not the JavaScript heap. Node's own docs suggest 1536 on a machine with 2 GiB. A value above the container's memory only replaces the heap error with the kernel killing the build, exit code 137.
Why does it build on my laptop and not on the server?
Your laptop has more memory than the build machine or container, and Node chooses its default heap limit from the memory it can see. Set the limit explicitly, then reduce what the build uses.
Is it safe to turn off type checking in next build?
Only if type checking runs somewhere else before you ship, for example in CI with tsc --noEmit. Next.js warns that ignoring type errors can produce faulty deploys.
Does exit code 137 mean the same thing?
It is also memory, but a different limit: the container's, not the heap's. The kernel killed the process, so Node had no chance to print heap out of memory. Lower the heap limit to fit the container, or give the build more memory.
Does Livops raise the heap limit for my build?
Yes, for a framework build. Unless you set NODE_OPTIONS yourself, Livops sets max-old-space-size to three quarters of the build container's memory. If the build still runs out, the log ends with a Tip on what to change.
Sources
- Node.js docs — Command-line API, --max-old-space-size (nodejs.org). Checked .
- Next.js docs — Optimizing memory usage (nextjs.org). Checked .
- Next.js docs — next CLI (nextjs.org). Checked .
Put your project online today
Connect GitHub or drop a folder. No card is asked for.
Deploy your Next.js appRelated
- npm ERR! code 1: why the build failed with exit code 1npm ERR! code 1 (npm error code 1 in newer npm) only says that a script npm ran exited with code 1. The real error is printed above it: usually a compile or type error, a lockfile out of sync with package.json, or a dependency whose install script failed. Find the first error line above code 1, fix that, and the build passes.
- App not listening on $PORT: why the health check failed after deployThe platform started your app, tried the port it gave it, and nothing answered in time. Almost always the app listens on its own fixed port instead of the PORT variable, listens on localhost (127.0.0.1) instead of 0.0.0.0, or crashed or was still starting when the check gave up. Listen on 0.0.0.0 and the port in PORT, and it passes.
- Error: listen EADDRINUSE: address already in use — how to fix itYour server tried to listen on a port that another process on the same machine already holds. On your computer, stop the old process, usually a dev server still running in another terminal. In a deploy, it almost always means the app starts its server twice, or two processes in one container ask for the same port.