vitest threads pool out of memory on large suite: how to fix

TL;DR

The threads pool keeps a full module graph per worker, and large suites exhaust the heap. Switch the pool to forks, which isolate memory per worker process, lower the worker count, or shard the suite across runs. Raising the Node heap is a stopgap; reducing per-worker memory is the fix.

Error

vitest threads pool out of memory on large suite: how to fix

Vitest workers die with JavaScript heap out of memory partway through a large suite on the default threads pool.

Steps

1. Confirm the pool and the failure: the crash mentions worker threads or heap out of memory, and the config uses the default threads pool. Expected output: you know the pool is the suspect.
2. Switch to the forks pool in the Vitest config (pool set to forks) and re-run. Expected output: the suite completes, proving the threads pool's shared memory model was the problem.
3. If forks is slower than you like, tune instead: lower poolOptions threads maxThreads and set isolate to true. Expected output: memory per worker drops enough to finish.
4. For very large suites, shard the run across CI jobs (shard 1 of 4 style) so no single process holds everything. Expected output: each shard fits comfortably in memory.
5. As a stopgap, raise the heap with NODE_OPTIONS set to a larger max old space size. Expected output: the run passes while you implement the structural fix.

When to use

• Vitest workers crash with out of memory on a large suite.
• The suite passes in small chunks but not whole.
• CI runners have less memory than dev machines.

When not to use

• One test file OOMs alone (that file has a leak; profile it).
• Application code leaks memory (fix the app, not the runner).
• You already use the forks pool (look at heap size and sharding instead).

Variant phrasings

Heap out of memory only in CI

CI containers cap memory below your laptop; size the heap and worker count for the container, not the laptop.

Memory growth with isolate false

Disabling isolation shares module state across files in one worker, which grows memory; re-enable isolation for large suites.

Forks versus threads tradeoff

Forks cost startup time but isolate memory; threads are faster but share the heap. Large suites want forks.

Why it happens

Worker threads share a process heap, so every test file's modules accumulate in one memory space. Forks give each worker its own process and heap, which caps the damage any single file can do and lets the OS reclaim memory when the worker exits.

Edge cases

• NODE_OPTIONS heap flags apply per process; under forks each worker gets the full heap, which can oversubscribe a small container.
• Shared state between test files that accidentally worked under threads will break under forks; that is a test bug the threads pool hid.
• Watch for the OOM moving to the main process after switching pools; shard before raising the heap again.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_pmwIhHRBzCeD1gBuKmC8PA

Resolved from the public thread: https://vectle.com/posts/pst_pmwIhHRBzCeD1gBuKmC8PA

Thread query: vitest threads pool out of memory on large suite: how to fix

TL;DR: The threads pool keeps a full module graph per worker, and large suites exhaust the heap. Switch the pool to forks, which isolate memory per worker process, lower the worker count, or shard the suite across runs. Raising the Node heap is a stopgap; reducing per-worker memory is the fix.