“JavaScript heap out of memory” during a build, and out-of-memory kills after it.

A build can run out of memory in two places, and the fixes point in opposite directions. Check which one you have before changing anything.

# The shape of a heap-limit failure (trimmed)
<--- Last few GCs --->
... Mark-Compact ... MB ...

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
 1: ... node::Abort() ...
 ...
# the process then exits with code 134

The flag sets the size of V8’s old-generation heap, in MiB. Node accepts it in NODE_OPTIONS, so it reaches every Node process your build script starts:

• Stay under the container’s memory. Node’s own docs suggest 1536 on a machine with 2 GiB, to leave room for everything outside the heap. Native modules, buffers and source maps held outside V8 all need memory too.
• Set it too high and you trade exit 134 for exit 137. The heap grows past what the container allows and the kernel kills the build with no message at all.
• Set it too low and you cause the error. A NODE_OPTIONS copied from an old README, such as --max-old-space-size=2048, caps a build that had 6 GB to use.

# One build, any shell that sets env vars this way (Linux, macOS)
NODE_OPTIONS=--max-old-space-size=3072 npm run build

# Check the limit Node is actually using, in MB
node -e "console.log(v8.getHeapStatistics().heap_size_limit / 1048576)"

Each build runs in its own sandbox with a memory budget set by your plan. Canner passes --max-old-space-size to the build for you, sized to that budget minus 200 MB for memory outside the heap, so most projects should not set it at all. The plans and limits docs list the numbers; the pricing page has the plans side by side.

• Find the peak. After each step the log prints a line like [canner] build used up to 3.4 GB of memory. Compare it with your budget before deciding what to change.
• When the build is killed, the message is build ran out of memory and was killed. On large projects this is often the type-checking or bundling step, followed by the Next.js fix below.
• When your own NODE_OPTIONS is the cause, Canner says so: “Your NODE_OPTIONS environment variable limits Node's heap to 2048 MB, well below the memory this build was given, so the build ran out of memory at that limit. Remove --max-old-space-size from NODE_OPTIONS (or raise it) and deploy again.” The automatic retry is skipped in that case, since more memory wouldn’t help.
• A retried build says why. Its log starts with [canner] the last build ran out of memory, so this one runs with more: 6 GB instead of your plan's 4 GB (once a month).

More memory hides the problem until the project grows again. For Next.js, these settings come from its own memory guide:

The running app has its own limit, separate from the build: 512 MB on Starter and 2 GB on Live. It is a hard cap. Past it, the kernel kills the process, and the Traffic & Memory chart on the project overview marks the moment as Out of memory, killed. The same chart draws memory against the limit, with each build marked, so a steady climb between deploys (a leak) looks different from jumps that follow traffic (real need).

Canner also warns before it gets there. When an app stays at or above 90% of its memory limit for 10 minutes, the organization’s owner gets an email, at most once per deploy and once a week per project.

To make Node collect garbage harder before the kernel steps in, set a heap limit below the app’s memory, for example --max-old-space-size=1536 for a 2 GB app. Add NODE_OPTIONS in Env Vars with the scope runtime only: that scope reaches the running app but never a build, so it can’t cap your build’s heap. Raising the limit won’t fix a leak; it only moves the crash later.

On a paid plan you can add memory to a project without changing plan. The two add-ons behave differently: