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.

<--- 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/...)

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.

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

Scope type-aware linting

1. Limit parserOptions.project to the files being linted, or use the newer projectService for lazier program construction.
2. Lint changed files only in pre-commit; reserve the full run for CI.
3. 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

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation