From 915d6c431764a041d54096180a17abe2ebcf93ce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ari=20Perkki=C3=B6?= <ari.perkkio@gmail.com>
Date: Fri, 26 Jan 2024 07:10:22 +0200
Subject: [PATCH] fix(threads): mention common work-around for the logged error
 (#5024)

---
 docs/guide/common-errors.md                 | 27 +++++++++++++++++++++
 packages/vitest/src/node/pools/threads.ts   |  2 +-
 packages/vitest/src/node/pools/vmThreads.ts |  2 +-
 3 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/docs/guide/common-errors.md b/docs/guide/common-errors.md
index 2dc78952c326..dde26b2d4249 100644
--- a/docs/guide/common-errors.md
+++ b/docs/guide/common-errors.md
@@ -58,3 +58,30 @@ sideEffect()
 
 vi.resetModules()
 ```
+
+## Failed to terminate worker
+
+This error can happen when NodeJS's `fetch` is used with default [`pool: 'threads'`](/config/#pool-1-0-0). This issue is tracked on issue [Timeout abort can leave process(es) running in the background #3077](https://github.com/vitest-dev/vitest/issues/3077).
+
+As work-around you can switch to [`pool: 'forks'`](/config/#forks) or [`pool: 'vmForks'`](/config/#vmforks).
+
+Specify `pool` in your configuration file:
+
+```ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    pool: 'forks',
+  },
+})
+```
+
+Or in your `package.json` scripts:
+
+```diff
+scripts: {
+-  "test": "vitest"
++  "test": "vitest --pool=forks"
+}
+```
diff --git a/packages/vitest/src/node/pools/threads.ts b/packages/vitest/src/node/pools/threads.ts
index 54a8067505f8..199736fd4e27 100644
--- a/packages/vitest/src/node/pools/threads.ts
+++ b/packages/vitest/src/node/pools/threads.ts
@@ -107,7 +107,7 @@ export function createThreadsPool(ctx: Vitest, { execArgv, env }: PoolProcessOpt
       catch (error) {
         // Worker got stuck and won't terminate - this may cause process to hang
         if (error instanceof Error && /Failed to terminate worker/.test(error.message))
-          ctx.state.addProcessTimeoutCause(`Failed to terminate worker while running ${files.join(', ')}.`)
+          ctx.state.addProcessTimeoutCause(`Failed to terminate worker while running ${files.join(', ')}. \nSee https://vitest.dev/guide/common-errors.html#failed-to-terminate-worker for troubleshooting.`)
 
         // Intentionally cancelled
         else if (ctx.isCancelling && error instanceof Error && /The task has been cancelled/.test(error.message))
diff --git a/packages/vitest/src/node/pools/vmThreads.ts b/packages/vitest/src/node/pools/vmThreads.ts
index 573382c3a013..f9e1b10da698 100644
--- a/packages/vitest/src/node/pools/vmThreads.ts
+++ b/packages/vitest/src/node/pools/vmThreads.ts
@@ -111,7 +111,7 @@ export function createVmThreadsPool(ctx: Vitest, { execArgv, env }: PoolProcessO
       catch (error) {
         // Worker got stuck and won't terminate - this may cause process to hang
         if (error instanceof Error && /Failed to terminate worker/.test(error.message))
-          ctx.state.addProcessTimeoutCause(`Failed to terminate worker while running ${files.join(', ')}.`)
+          ctx.state.addProcessTimeoutCause(`Failed to terminate worker while running ${files.join(', ')}. \nSee https://vitest.dev/guide/common-errors.html#failed-to-terminate-worker for troubleshooting.`)
 
         // Intentionally cancelled
         else if (ctx.isCancelling && error instanceof Error && /The task has been cancelled/.test(error.message))