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.

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