Introducing Livops 2.0! Promo codeCEOgives you 8,000 so‘m on your balance.What’s new

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; --webpack switches to Webpack[3]. If you build with Webpack, experimental.webpackMemoryOptimizations: true lowers 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-size to three quarters of the build container’s memory, so Node can use the memory the build has instead of guessing low. If you set NODE_OPTIONS in 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 as build_failed, and the log ends with a Tip: line: set NODE_OPTIONS in 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.config on its own.
  • The running app is sized separately. next start runs with the service’s memory tier — its type’s default, 512, 1024 or 2048 MiB — which you can set with memory in livops.json when 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

  1. Node.js docs — Command-line API, --max-old-space-size (nodejs.org). Checked .
  2. Next.js docs — Optimizing memory usage (nextjs.org). Checked .
  3. 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 app

Got a question? — @livops_uz