JavaScript Heap Out of Memory in GitHub Actions: Fix
Last updated
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory means a Node.js process used up its V8 heap limit and aborted. It is a different failure from the kernel killing the process (exit code 137): here Node stops itself, because the limit it was given is too small for the work. Bundlers, TypeScript compiles, ESLint and Jest on large projects hit it first. npm ERR! code ENOMEM is the related case where the machine itself cannot allocate memory.
The exact message
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
<--- Last few GCs --->
Aborted (core dumped)
npm ERR! code ENOMEM
npm ERR! errno ENOMEM
npm ERR! Cannot allocate memory
After the V8 message the step usually ends with a non-zero exit code, often 134, which is SIGABRT.
Fix 1: raise the heap limit, below the runner's RAM
Node's default heap limit depends on the Node version and the memory of the machine, and large builds can exceed it. Set it with NODE_OPTIONS, in megabytes:
- run: npm run build
env:
NODE_OPTIONS: --max-old-space-size=6144
Keep the number below the RAM of the runner with room for the OS and other processes. A standard private-repository Linux runner has far less memory than a developer laptop, so a limit that works locally can push the machine into swap, or lead to an out-of-memory kill instead. Check the runner specs for the machine you use.
Fix 2: set it for one tool, not the whole job
NODE_OPTIONS applies to every Node process in the step, including the package manager. To raise the limit for just one command:
- run: node --max-old-space-size=6144 ./node_modules/.bin/tsc -p tsconfig.json
- run: node --max-old-space-size=4096 ./node_modules/.bin/eslint .
Fix 3: use less memory
- Turn off source maps in CI builds, or generate them in a separate job.
- Run the type check, the lint and the bundle as separate steps or jobs, so their heaps do not add up in one process.
- For Jest, limit workers and restart leaky ones:
- run: npx jest --maxWorkers=2 --logHeapUsage
- For TypeScript monorepos, use project references and incremental builds so that one process does not load everything at once.
- Remove large dependencies that are only needed in development from the build graph.
Fix 4: npm ERR! code ENOMEM
ENOMEM during npm ci or npm install means the machine ran out of memory while unpacking or running install scripts. Free memory by running fewer steps in parallel, by not starting services in the background before install, and by using a runner with more memory. Postinstall scripts that compile native modules are a common cause.
Fix 5: add RAM
If you have tuned the limits and the build still needs more, give it a bigger machine. Options are a GitHub larger runner, or a provider such as compiler.dev, whose default Linux machine is 8 vCPU with 16 GB (see pricing). Switching is a change to runs-on.
How to prevent it
- Record peak memory in CI and alert when it passes about 75% of the runner's RAM.
- Set
--max-old-space-sizeexplicitly instead of relying on defaults. - Watch bundle size and test memory when upgrading dependencies.
- Keep one heavy Node process per step.
FAQ
What is the default Node.js heap limit?
It depends on the Node version and the system memory, so there is no single number. Check it with node -e "console.log(v8.getHeapStatistics().heap_size_limit / 1048576)" on the runner.
Is this the same as exit code 137?
No. 137 means the operating system killed the process. This error is Node aborting itself when its own heap limit is reached, and it is usually fixed by raising --max-old-space-size.
Why does it pass locally?
Your laptop has more memory and Node picks a larger default heap. CI machines are smaller and fixed.
Can I set the limit in package.json?
Yes, for example "build": "node --max-old-space-size=6144 node_modules/vite/bin/vite.js build". Setting NODE_OPTIONS in the workflow is simpler.
Related
- Cache Service Responded With 429: FixFix "Failed to restore: Cache service responded with 429" in GitHub Actions: too many cache requests. Upgrade actions/cache, restore once, save once.
- fatal: could not read Username for github.com: FixFix "fatal: could not read Username for 'https://github.com'" in GitHub Actions: private repos, submodules and git dependencies need a token.
- Invalid Workflow File: YAML Syntax Error FixFix "Invalid workflow file" and "You have an error in your yaml syntax" in GitHub Actions: indentation, unexpected value, bad expressions, with actionlint.
- Permission Denied (publickey) in GitHub Actions: FixFix "git@github.com: Permission denied (publickey)" in GitHub Actions: add an SSH key or deploy key, or switch to an HTTPS token for private repos.