vitest worker exited unexpectedly: how to fix

Not specified by the original author.

TL;DR

Switch the pool to forks or cut the worker count; most unexpected exits are workers running out of memory. Run with --pool=forks --maxWorkers=2 as a first test. If the run goes green, tune from there instead of chasing a flaky test.

Error

Vitest worker exited unexpectedly

Steps

1. Re-run with a smaller worker pool: npx vitest run --pool=forks --maxWorkers=2. Expected: the run completes instead of the worker dying mid-suite.
2. If it passes, raise the worker count gradually or add pool options in the vitest config to make it permanent. Expected: stable green runs at your chosen worker count.
3. Look for process.exit calls, unhandled rejections, or native module crashes in the failing file; isolate it with npx vitest run path/to/file. Expected: you find the single file that kills the worker.
4. On CI containers, also raise container memory or set --maxWorkers to the container CPU count. Expected: no more exits under CI load.

When to use

• Vitest 2 or 3 prints a worker-exited message and the run aborts.
• Failures cluster on large suites or memory-heavy tests.
• CI fails while the same suite passes locally.

When not to use

• A single test fails with an assertion error; that is a test bug, not a worker crash.
• The error names a missing module; fix the import instead.
• You are on Vitest 1; pool option names differ there.

Tool compatibility

• Vitest 2.x and 3.x: --pool=forks or --pool=threads, plus --maxWorkers and --minWorkers flags.
• Node 18, 20, 22: the forks pool is the safer default on constrained machines.

Variant phrasings

vitest worker crashed

Same thing under different wording; the pool and memory steps apply.

vitest run hangs then exits with no output

Often the same out-of-memory kill; check container memory limits and your CI provider's OOM signals.

Why it happens

Vitest runs test files in worker threads or forked processes with a fixed memory ceiling. A leak, a huge import graph, or too many parallel workers pushes a worker past that ceiling and the OS kills it, which Vitest reports as an unexpected exit.

Edge cases

• A native module that is not thread-safe crashes only under the threads pool; forks fixes it permanently.
• Reporters that buffer output can hide which file died; rerun with default output to find it.
• If a single file kills even one forked worker, the file itself is the bug; bisect its tests.

Provenance

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

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

Thread query: vitest worker exited unexpectedly: how to fix

TL;DR: Switch the pool to forks or cut the worker count; most unexpected exits are workers running out of memory. Run with --pool=forks --maxWorkers=2 as a first test. If the run goes green, tune from there instead of chasing a flaky test.

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

Some promise in the suite rejected with no .catch() anywhere, and vitest fails the run on unhandled rejections instead of letting them vanish. The rejection often comes from a timer callback, a fire-and-forget fetch, or an event handler, and CI timing decides whether it surfaces. Attach a temporary unhandledRejection listener that prints the full stack, run the suite until it fires, then await the promise or add a catch at its source.

The query

vitest Unhandled Rejection failing CI  -  how to find the floating promise

Use this when

• vitest fails CI with Unhandled Rejection and no test name attached
• the failure is intermittent and moves between runs
• the stack, once printed, points into app or test async code

Not for

• an error thrown synchronously inside a test (that already has a test name and stack)
• a rejection the application intentionally logs and handles (not unhandled at all)
• the run fails for a different reason and the rejection is a side effect; fix the primary failure first

Steps

1. Add a temporary listener that prints the rejection stack

Put this in a setup file or at the top of the failing test file. The stack is the only thing that identifies a floating promise.

// debug-setup.js (temporary)
process.on('unhandledRejection', (reason) => {
  console.error('UNHANDLED REJECTION:', reason && reason.stack || reason);
  process.exitCode = 1;
});

Expected output: the listener is registered before any test code runs.

2. Run the suite until the rejection fires

Run the same command CI runs. It may take a few attempts if the rejection is timing-dependent; the stack print makes each attempt informative.

npx vitest run --setupFiles ./debug-setup.js 2>&1 | grep -A25 "UNHANDLED REJECTION"

Expected output: the printed stack points at the exact line that created the floating promise.

3. Fix the promise at its source

Await it, return it to the caller, or attach a .catch(). Do not just add a global handler and move on; the handler is a diagnostic tool.

// before: fire-and-forget
fetch('/api/sync');
// after: awaited or handled
await fetch('/api/sync');

Expected output: the rejection is handled where it originates and the temporary listener stays silent.

4. Remove the debug listener and keep the suite strict

Delete the temporary setup file. Vitest already fails on unhandled rejections by default, which is the behavior you want guarding the suite going forward.

rm debug-setup.js
npx vitest run

Expected output: the suite passes cleanly with no debug scaffolding left behind.

Tool compatibility

• vitest 1 - 3
• Node 18 - 22

Variant phrasings

• vitest Unhandled Rejection failing CI
• Unhandled Rejection in vitest with no stack trace
• PromiseRejectionHandledWarning in CI test output

Why it happens

A promise with no rejection handler is a silent bug: Node reports it to the process, not to any test. Vitest opts into failing the run on these because an unobserved rejection usually means the code under test never finished its work. CI surfaces them more often because different timing changes which promises settle after the test that created them has already finished.

Edge cases / pitfalls

• rejections inside setTimeout, setInterval, or event-emitter callbacks are the classic floaters; search those first
• dangerouslyIgnoreUnhandledErrors makes the failure go away by hiding it; never ship that as the fix
• an async test function that forgets to await its last call can produce a rejection attributed to the next test file; the stack still shows the origin
• third-party libraries with background promises can be the source; the stack distinguishes your code from theirs

Provenance

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

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

Thread query: vitest Unhandled Rejection failing CI - how to find the floating promise

TL;DR: Some promise in the suite rejected with no .catch() anywhere, and vitest fails the run on unhandled rejections instead of letting them vanish. The rejection often comes from a timer callback, a fire-and-forget fetch, or an event handler, and CI timing decides whether it surfaces. Attach a temporary unhandledRejection listener that prints the full stack, run the suite until it fires, then await the promise or add a catch at its source.