Skip to main content
Castov
TypeScript & Node.js · Developer Error Resolution Lab

Fix Node.js 'FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory'

Increase V8 memory allocation using --max-old-space-size and identify memory leaks during builds.

Triggered Error Message:

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Customize Solution for Your Environment
# Linux / macOS:
export NODE_OPTIONS="--max-old-space-size=8192"
npm run build

# Windows PowerShell:
$env:NODE_OPTIONS="--max-old-space-size=8192"
npm run build

# Add directly to package.json scripts:
"scripts": {
  "build": "cross-env NODE_OPTIONS=--max-old-space-size=8192 next build"
}

Root Cause & Mechanism Analysis

Why does this error occur?

Node.js defaults to ~2GB to 4GB of RAM heap limit. Heavy builds (Next.js Turbopack, Webpack, large TypeScript ASTs) or unreleased object references exceed the default quota.

Frequently Asked Questions

What is the recommended heap limit for Next.js builds on CI/CD?
Setting 4096MB (4GB) or 8192MB (8GB) is standard on GitHub Actions / Vercel agents with sufficient host RAM.

Related Developer Error Solutions

Browse All 35 Guides
TypeScript & Node.js

Node.js: ERR_OSSL_EVP_UNSUPPORTED

Resolve OpenSSL 3.0 cryptographic deprecation errors in Node.js 17+ when running Webpack 4 or legacy build tools.

View fix guide
TypeScript & Node.js

Webpack: Module parse failed

Configure appropriate loaders for TypeScript, JSX, CSS modules, or modern JavaScript syntax.

View fix guide
DevOps & Docker

Docker: no space left on device

Clean dangling Docker build caches, unused volumes, and stopped containers to free disk space.

View fix guide