TypeScript "Reached heap limit Allocation failed" (tsc) in CI

tsc exhausted the V8 heap while type-checking. Large projects, heavy generics, or skipLibCheck disabled across many .d.ts files can push memory past the default limit and crash the compile.

What this error means

A tsc build fails with FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory. It often appears only in CI, where the runner has less RAM than a dev machine.

node

<--- Last few GCs --->
[1:0x...] FATAL ERROR: Reached heap limit Allocation failed -
JavaScript heap out of memory
 1: 0x... node::Abort()

Common causes

The project is too large for the default heap

A big type graph, deep generics, or broad .d.ts checking consumes more than the default ~2 GB heap on a small runner.

Unnecessary lib checking

Leaving skipLibCheck off forces tsc to type-check every dependency declaration, multiplying memory use.

How to fix it

Raise the heap and trim lib checking

Give Node more heap and skip checking library declarations.

workflow

NODE_OPTIONS=--max-old-space-size=8192 tsc -p tsconfig.json
# and in tsconfig.json: "skipLibCheck": true

Split the build with project references

Break a monolithic compile into smaller referenced projects so each compiles within budget.

Introduce TypeScript project references for large workspaces.
Build with tsc -b so projects compile incrementally.
Enable skipLibCheck to drop redundant lib type-checking.

How to prevent it

Enable skipLibCheck for large projects.
Use project references / incremental builds to bound memory per compile.
Match CI runner RAM to the project type-checking cost.