fix(threads): mention common work-around for the logged error (#5024)

Author: AriPerkkio

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"
+}
+```

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))

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))