Seeing the JavaScript heap out of memory error while running a Node.js build can be frustrating. The process starts normally, consumes more memory, and then crashes before the build finishes. This often happens with large projects, but it does not always mean you need a bigger computer.

The error means Node.js has reached the memory limit available to its JavaScript engine, V8. Increasing that limit can help, but the right fix depends on whether your build genuinely needs more memory, your code is using memory inefficiently, or your environment has a strict memory limit.

Here is how to troubleshoot the problem without blindly changing your system configuration.

1. Try increasing the Node.js heap limit

For a large frontend or Node.js project, the quickest test is to increase the maximum old-space heap size using the --max-old-space-size option.

On macOS or Linux, open a terminal in your project directory and run:

NODE_OPTIONS=--max-old-space-size=4096 npm run build

On Windows PowerShell, use:

$env:NODE_OPTIONS="--max-old-space-size=4096"
npm run build

On the Windows Command Prompt, use:

set NODE_OPTIONS=--max-old-space-size=4096 && npm run build

These commands allow Node.js to use up to 4096 MiB, approximately 4 GiB, for the V8 old-space heap. This is a heap limit, not a guarantee that the entire process will fit within 4 GB of RAM.

Choose a limit that leaves enough memory for your operating system and other running processes. Do not automatically allocate 4 GB on a machine or CI runner that has only a small amount of RAM available.

If your project uses pnpm or Yarn, replace npm run build with the corresponding command, such as pnpm build or yarn build.

2. Confirm which process is running out of memory

Before making the change permanent, check where the error occurs. Does it happen during a production build, while running tests, during development, or after your server has been running for some time?

The distinction matters. A build failure may point to bundling, compilation, source maps, or unusually large files. A long-running server that gradually consumes more memory may have a memory leak or retain objects it no longer needs.

Check your Node.js version with:

node -v

Then rerun the exact command that failed and inspect the log leading up to the error. If the failure consistently occurs while compiling a particular module or processing a large file, investigate that operation instead of treating the heap limit as the only possible cause.

3. Check the available memory on your machine or CI runner

Increasing the Node.js heap limit cannot create physical memory. Your process also needs memory for native code, buffers, the operating system, and other work taking place at the same time.

This is particularly important when the build runs inside Docker, a CI/CD pipeline, or a cloud development environment. The environment running Node.js may have a smaller memory allowance than the host machine itself.

For example, setting the heap limit to 4 GB will not solve a problem if the container is restricted to less memory than the process needs. The container or operating system may terminate the process before Node.js reaches its configured heap limit.

Check your runner’s memory allocation and any Docker or platform-specific resource limits. If the available memory is insufficient, reduce the build’s memory requirements or provide an environment with adequate resources.

4. Reduce the amount of work your build has to do

If the error continues even with a reasonable heap limit, look for opportunities to reduce peak memory usage. These are common places to investigate:

• Oversized imports: Check whether the application imports large JSON files, datasets, or assets that do not need to be bundled into the application.
• Large source maps: Source map generation can add memory overhead in some build pipelines. Test your build with a different source map configuration if your tooling supports it, while considering the debugging impact.
• Unnecessary files in compilation: Review your TypeScript configuration and build inputs to ensure generated output, test fixtures, or unrelated files are not being compiled unnecessarily.
• Large in-memory operations: If a script reads a huge file or dataset all at once, consider streaming it or processing it in smaller batches instead of retaining the entire dataset in memory.
• Expensive build steps: If your project supports independent packages or applications, try building them separately to identify which step causes memory usage to spike.

For larger projects, making one targeted change at a time helps you identify the actual cause rather than introducing several changes that are difficult to evaluate.

5. Investigate a possible memory leak

If a Node.js process starts with relatively low memory usage and continues consuming more memory over time, investigate whether your code is retaining objects unnecessarily.

Common causes include unbounded caches, collections that keep growing, event listeners that are never removed, and references that prevent objects from being garbage-collected.

For deeper investigation, Node.js supports diagnostic reports that can capture runtime information, JavaScript and native stack traces, and heap statistics when a fatal error occurs.

For example, on macOS or Linux, you can enable a report for a fatal error during reproduction:

NODE_OPTIONS="--report-on-fatalerror" npm run build

Keep any generated diagnostic report private until you have checked it for sensitive paths, environment details, or other information you should not publish. The report can help with diagnosis, but it does not automatically identify or repair the underlying cause.

6. What if the build still fails?

If increasing the heap limit does not help, verify that the setting reaches the Node.js process that actually performs the failing work. Some build tools launch child processes, run inside containers, or have their own environment configuration.

Also check whether the message is genuinely a V8 heap error. A process that exits with a message such as Killed may have been terminated by the operating system or container environment rather than by V8’s heap limit.

Avoid repeatedly increasing the heap to very large values without investigating memory consumption. That can delay the failure while making the machine slower or less stable.

Frequently asked questions

Is increasing the Node.js heap limit safe?

It is a normal troubleshooting step when a build legitimately needs more memory. However, choose a value based on the memory available to the process. A larger limit can worsen system memory pressure if the machine or container cannot support it.

Will this fix the error in Angular, Next.js, or other frontend builds?

It can help when the build tool runs in Node.js and the failure is caused by V8 reaching its heap limit. It will not fix every build failure, particularly when the root cause is a memory leak, an operating-system memory limit, or a problem unrelated to heap allocation.

Should I delete node_modules to fix this error?

Not as the first step. Reinstalling dependencies may help with certain dependency or installation problems, but it does not directly increase the JavaScript heap limit. Start by checking the error, available memory, and the build process that is consuming it.

Final thoughts

The JavaScript heap out of memory error in Node.js is often resolved by increasing the heap limit to a sensible value. But the most reliable fix is to understand why the process needs that memory in the first place.

Start with the heap setting, check the resources available to the process, and then investigate large build inputs or potential memory leaks if the error persists. That approach is more effective than continuously increasing the limit and hoping the next build succeeds.

For the exact supported options, refer to the official Node.js command-line documentation, the Node.js diagnostic report guide, and the Docker resource constraints documentation.