JavaScript heap out of memory during next build

Node.js keeps JavaScript objects in V8's heap, and the long-lived part of it, old space, has a maximum size. As memory use nears that limit, V8 spends more and more time collecting garbage. When a collection can't free enough, V8 stops the process and prints one of these:

<--- Last few GCs --->
...
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

# or, from older Node versions
FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

The limit is V8's, not the machine's. A laptop with 16 GB of RAM can still hit it, because Node picks its default heap size from the memory it detects and doesn't grow past it. A build that worked last month fails today because the app grew: more pages, more dependencies, a bigger type graph.

Two different failures look alike in a build log. Tell them apart before you fix anything:

The second case is why the usual advice, --max-old-space-size=8192, sometimes “fixes” the heap error and replaces it with exit code 137. A heap limit above the memory the build really has lets V8 keep allocating until the kernel kills it.

Pass --max-old-space-size, in MiB, to the Node process that runs the build. Put it in the build script, so it applies to the build and not to the server you run afterwards:

// package.json
"scripts": {
  "build": "NODE_OPTIONS=--max-old-space-size=3072 next build",
  "start": "next start"
}

// The same without an environment variable (works in any shell)
"build": "node --max-old-space-size=3072 node_modules/next/dist/bin/next build"

The first form needs a Unix shell; on Windows use cross-env or the second form. Pick a number below the memory the build machine has, leaving room for everything outside the heap. Node's own docs suggest 1536 on a machine with 2 GiB. Rough guide:

Setting NODE_OPTIONS as an environment variable on your host also works, but it reaches every Node process, including the production server. A 3 GB heap limit on a server container with 512 MB of memory turns a slow garbage collection into an OOM kill.

Read the last line next build printed before the crash. Each step has its own fix, all from the Next.js memory usage guide:

Skipping the type check is safe only if something else runs it. The Next.js docs warn that it “may produce faulty deploys due to type errors”, so add tsc --noEmit to CI or a pre-push hook before you turn it off.

// next.config.ts
import type { NextConfig } from 'next'

const config: NextConfig = {
  productionBrowserSourceMaps: false,
  experimental: {
    serverSourceMaps: false,
  },
  typescript: {
    // only with tsc --noEmit running in CI
    ignoreBuildErrors: true,
  },
}

export default config

Next.js 16 builds with Turbopack by default. If your build runs next build --webpack, or you are on Next.js 15 or older, three webpack settings cut memory use:

• experimental.webpackMemoryOptimizations: true (Next.js 15 and later) lowers peak memory at the cost of slightly slower compiles. Next.js calls it low-risk.
• experimental.webpackBuildWorker: true runs compilation in a separate worker. It is on by default since 14.1 unless you have a custom webpack config, so check this one if you do.
• Webpack's persistent cache holds modules in memory. The Next.js guide shows how to switch it to the memory-only cache in production builds:

webpack: (config, { dev }) => {
  if (config.cache && !dev) {
    config.cache = Object.freeze({ type: 'memory' })
  }
  return config
},

If the limit keeps climbing, measure before raising it again:

# Print heap use and GC stats through the build; snapshots near the limit
next build --experimental-debug-memory-usage

# Write a .heapprofile to load in Chrome DevTools > Memory
node --heap-prof node_modules/next/dist/bin/next build

The debug mode doesn't work with the webpack build worker. In the profile, look for one package that owns a large share of allocations: an icon set imported whole, a large JSON file, a charting library pulled into every page. The bundle analyzer shows the same thing from the output side, and removing or lazy-loading one large dependency often does more than any setting above.

EthioDeploy builds your app in a separate build container, so a build that runs out of memory fails the deploy and the previous version keeps serving traffic. The build log shows the same FATAL ERROR line or an exit code 137 as anywhere else, and the fixes above apply as written.

Put --max-old-space-size in the build script, not in a NODE_OPTIONS environment variable. Project environment variables reach both the build and the running app, and on the Free plan the app container caps the Node heap below its 256 MB memory limit so Node collects garbage before the kernel kills it. A --max-old-space-size of your own in NODE_OPTIONS replaces that cap, so a value sized for the build would also apply to the 256 MB server. The deploy log says when the cap is applied.

If your app needs more memory at runtime too, see pricing for plan limits, and Deploy Next.js for the full setup.