ESLint "JavaScript heap out of memory" on Large Repos in CI

By Daniel Zoghalchali·Latchkey

Linting a large repo - especially with type-aware typescript-eslint rules that build a full TypeScript program - can exhaust V8's heap. ESLint aborts with the same OOM as any other Node process.

What this error means

ESLint dies with FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory, usually on big monorepos or with type-checked rules enabled, on a smaller runner.

eslint

<--- Last few GCs --->
[1:0x...] Mark-sweep ... -> 2046.0 MB, ...
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
    at Object.lint (/app/node_modules/eslint/lib/...)

Diagnose it: config resolution and version drift

Lint failures that appear only in CI are almost always a different linter version or a different resolved configuration, not new violations in the code.

Terminal

npx eslint --version
npx eslint --print-config path/to/file.ts | head -40
npx eslint --debug path/to/file.ts 2>&1 | grep -i "config" | head

Common causes

Type-aware rules build a large TS program

typescript-eslint rules with parserOptions.project construct a full type program; on a big repo that program plus the AST can exceed the default heap.

Constrained runner linting everything at once

Linting the whole repo in one process on a small runner leaves Node less RAM than the peak it needs.

How to fix it

Raise the heap and cache results

Give Node more old-space and reuse the ESLint cache between runs.

Terminal

export NODE_OPTIONS=--max-old-space-size=4096
npx eslint . --cache --cache-location .eslintcache

Scope type-aware linting

Limit parserOptions.project to the files being linted, or use the newer projectService for lazier program construction.
Lint changed files only in pre-commit; reserve the full run for CI.
Shard linting across packages in a monorepo instead of one giant process.

How to prevent it

Cache ESLint results and scope type-aware rules.
Set a sensible --max-old-space-size for the lint job.
Faster managed runners such as Latchkey provide more RAM and dependency caching so large-repo lint runs complete under the heap ceiling and transient OOMs are auto-retried.

Frequently asked questions

What causes ESLint "JavaScript heap out of memory" on large repos in CI?

There are 2 common causes: type-aware rules build a large ts program and constrained runner linting everything at once. typescript-eslint rules with parserOptions.project construct a full type program; on a big repo that program plus the AST can exceed the default heap.

How do I fix ESLint "JavaScript heap out of memory" on large repos in CI?

There are 2 fixes depending on which cause you have: raise the heap and cache results and scope type-aware linting. Work through them in order, since the first is the most common.

What does ESLint "JavaScript heap out of memory" on large repos in CI actually mean?

ESLint dies with FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory, usually on big monorepos or with type-checked rules enabled, on a smaller runner.

How do I stop ESLint "JavaScript heap out of memory" on large repos in CI happening again?

Cache ESLint results and scope type-aware rules. The prevention section lists 3 changes that keep it from recurring.

Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.