feat(vitest-pool-workers): tolerate post-stop() socket error events when configured by trafgals · Pull Request #14794 · cloudflare/workers-sdk

trafgals · 2026-07-21T21:57:15Z

What

When workerd segfaults during shutdown (cloudflare/workerd#6763), miniflare's WebSocket dispatches an error event after every test in the file has already been reported as passing. vitest then surfaces this as [vitest-pool]: Worker cloudflare-pool emitted error and fails the run with exit 1.

This change adds a new opt-in tolerateWorkerShutdownErrors: boolean option to the cloudflare-pool worker configuration. When enabled, error events received after stop() has begun are logged via NODE_DEBUG=vitest-pool-workers and not propagated to vitest as fatal errors. The default behavior is unchanged.

Relationship to #14793

This PR is intentionally distinct from #14793 (which wraps Miniflare#dispose() and the remote-proxy session dispose() with .catch()). The two changes tolerate different amplifiers in the same root-cause chain:

fix(vitest-pool-workers): tolerate dispose rejections in pool worker stop() #14793: tolerates stop()'s dispose promises rejecting when workerd crashes during teardown.
This PR: tolerates the WebSocket error event that miniflare emits when the workerd subprocess exits unexpectedly — which can fire after stop() has begun (or during teardown of the next test file's worker).

Both are useful. They can be enabled together or independently. Neither fixes the underlying workerd SIGSEGV — that needs to be done in workerd itself.

Root-cause recap

The workerd SIGSEGV is the trigger; the test-side non-zero exit is three layers deep:

workerd subprocess dies during shutdown (upstream bug).
The dispose promises in CloudflarePoolWorker.stop() reject with that segfault (mitigated by fix(vitest-pool-workers): tolerate dispose rejections in pool worker stop() #14793).
The WebSocket dispatches an error event AFTER stop() begins, which vitest surfaces as fatal. (mitigated by this PR)
tinypool's ProcessWorker.onUnexpectedExit also emits Worker exited unexpectedly for forks that exit while idle — this is mitigated by the new allowWorkerIdleExit opt-in in feat: add allowWorkerIdleExit option to suppress idle-worker error events tinylibs/tinypool#133.

Reproduction

Tests  794 passed (794)
❌ vitest exit 1
[vitest-pool]: Worker cloudflare-pool emitted error.
Caused by: Worker exited unexpectedly

With tolerateWorkerShutdownErrors: true, the same suite reports 794 passed and exits 0. The segfault is still printed to stderr; only the test-side exit suppression changes.

Implementation notes

The stopping flag is set at the very start of stop() so any error event that fires after that point — including ones that fire synchronously from socket.close() — sees the same state.
Errors raised while a task is in flight are still propagated unchanged. Only post-stop() error events are inspected.
The debug logging uses the same util.debuglog(vitest-pool-workers) channel the rest of the package uses for diagnostic logs.
Marks the message with the upstream issue URL so anyone seeing it during teardown can immediately find context.
Adds a patch-level changeset.

Partial fix (test-side amplifier wrangler publish #2) of Bug: workerd segfaults intermittently on shutdown under vitest-pool-workers (linux-x64 and macOS-arm64) workerd#6763.
Complements fix(vitest-pool-workers): tolerate dispose rejections in pool worker stop() #14793 (test-side amplifier wrangler dev #1).
Cross-references the workerd comment at Bug: workerd segfaults intermittently on shutdown under vitest-pool-workers (linux-x64 and macOS-arm64) workerd#6763 (comment) and Bug: workerd segfaults intermittently on shutdown under vitest-pool-workers (linux-x64 and macOS-arm64) workerd#6763 (comment).

🤖 Generated with Claude Code

workerd can segfault during shutdown on linux-x64 / WSL2 and macOS-arm64 (cloudflare/workerd#6763). After every test in a file has already reported as passing, the segfault propagates as a WebSocket `error` event which vitest surfaces as `[vitest-pool]: Worker cloudflare-pool emitted error`, failing an otherwise-passing run with exit 1. Add an opt-in `tolerateWorkerShutdownErrors: boolean` option (default `false`). When enabled, `error` events received after `stop()` has begun are logged via `NODE_DEBUG=vitest-pool-workers` and not forwarded to vitest as fatal. Errors received while the pool worker is still running are propagated unchanged. This complements the dispose-side fix in cloudflare#14793 (which wraps the Miniflare and remote-proxy session `dispose()` calls with `catch()`): the dispose fix tolerates teardown promise rejections, while this option tolerates the post-teardown WebSocket `error` event. Both opt-in; both default `false`. Reproduction (matches the linked upstream issue): Tests 794 passed (794) ❌ vitest exit 1 [vitest-pool]: Worker cloudflare-pool emitted error. Caused by: Worker exited unexpectedly With `tolerateWorkerShutdownErrors: true`, the same suite reports `794 passed` and exits 0. The segfault is still printed to stderr under `NODE_DEBUG=vitest-pool-workers`; only the test-side exit suppression changes. Scope is a test-side mitigation only — the upstream `Received signal cloudflare#11` still needs to be fixed in workerd itself.

changeset-bot · 2026-07-21T21:57:21Z

🦋 Changeset detected

Latest commit: 0f8d2c8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cloudflare/vitest-pool-workers	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

workers-devprod · 2026-07-21T21:57:44Z

Codeowners approval required for this PR:

@cloudflare/wrangler

Show detailed file reviewers

.changeset/pool-worker-tolerate-shutdown-socket-errors.md: [@cloudflare/wrangler]
packages/vitest-pool-workers/src/pool/cloudflare-pool-worker.ts: [@cloudflare/wrangler]
packages/vitest-pool-workers/src/pool/config.ts: [@cloudflare/wrangler]

devin-ai-integration

Devin Review found 2 potential issues.

devin-ai-integration · 2026-07-21T21:59:10Z

+"@cloudflare/vitest-pool-workers": patch
+---
+
+fix: tolerate post-`stop()` socket `error` events when configured


🟡 Changeset title uses a forbidden conventional-commit prefix

The changeset headline starts with a fix: type prefix (.changeset/pool-worker-tolerate-shutdown-socket-errors.md:5), which the repository's review guidelines explicitly forbid for changeset titles.
Impact: The changelog entry will be formatted against the project's stated conventions and may require rework before release.

Rule source in REVIEW.md

REVIEW.md's Changesets section states: "Do NOT prefix changeset titles with a 'type' (e.g. fix:, feat:, chore:). The changeset title should be a plain description without conventional commit prefixes." The title on .changeset/pool-worker-tolerate-shutdown-socket-errors.md:5 begins with fix:.

Suggested change

fix: tolerate post-`stop()` socket `error` events when configured

Tolerate post-`stop()` socket `error` events when configured

Was this helpful? React with 👍 or 👎 to provide feedback.

edmundhung · 2026-07-24T15:06:42Z

+workerd can segfault (`Received signal #11`) during shutdown on linux-x64 /
+WSL2 and macOS-arm64 (see
+[cloudflare/workerd#6763](https://github.com/cloudflare/workerd/issues/6763)).
+After all tests in a file have already reported as passing, the segfault causes
+miniflare's WebSocket to dispatch an `error` event; vitest then surfaces that
+as `[vitest-pool]: Worker cloudflare-pool emitted error` and fails the run
+with exit 1.
+
+This change adds an opt-in `tolerateWorkerShutdownErrors: boolean` option
+(default `false`) to the cloudflare-pool worker configuration. When enabled,
+`error` events received after `stop()` has begun are logged via
+`NODE_DEBUG=vitest-pool-workers` but not forwarded to vitest as fatal. Errors
+received while the pool worker is still running are still propagated
+unchanged.
+
+This change does **not** alter the behavior of `stop()` itself — for the
+dispose-side fix, see #14793 (which wraps `Miniflare#dispose()` and the
+remote-proxy session `dispose()` with `.catch()` handlers). Pairing both
+options (`tolerateWorkerShutdownErrors: true` + the dispose fix) is what
+produces a fully-shutdown-tolerant run.
+
+Scope is a test-side mitigation only — the upstream `Received signal #11`
+itself still needs to be fixed in workerd itself.
+
+Reproduction (matches
+[cloudflare/workerd#6763](https://github.com/cloudflare/workerd/issues/6763)):
+
+```
+Tests  794 passed (794)
+❌ vitest exit 1
+[vitest-pool]: Worker cloudflare-pool emitted error.
+Caused by: Worker exited unexpectedly
+```
+
+With `tolerateWorkerShutdownErrors: true`, the same suite reports `794 passed`
+and exits 0. The segfault is still printed to stderr; only the test-side exit
+suppression changes.


The changeset should focus more on user impact. You can use #14793 for reference.

edmundhung · 2026-07-24T15:07:19Z

+	// Used to log non-fatal socket errors (e.g. workerd shutdown segfaults —
+	// see https://github.com/cloudflare/workerd/issues/6763) without surfacing
+	// them to vitest when configured to tolerate them.
+	private readonly debug = util.debuglog("vitest-pool-workers");


I think you added this in #14793 already? Please rebase and resolve the conflict.

edmundhung · 2026-07-24T15:10:15Z

+	// from the runner socket should be suppressed (see
+	// https://github.com/cloudflare/workerd/issues/6763 and the
+	// `tolerateWorkerShutdownErrors` config option).


There is no need to refer to the workerd issue in the comment. I will just treat this as a generic hardening.

This applies to the rest of the comments too.

edmundhung · 2026-07-24T15:12:40Z

+					this.debug(
+						"ignoring socket `error` during teardown (tolerateWorkerShutdownErrors=true; see cloudflare/workerd#6763): %s",
+						errorValue instanceof Error
+							? errorValue.stack ?? errorValue.message
+							: errorValue
+					);


Suggested change

this.debug(

"ignoring socket `error` during teardown (tolerateWorkerShutdownErrors=true; see cloudflare/workerd#6763): %s",

errorValue instanceof Error

? errorValue.stack ?? errorValue.message

: errorValue

);

this.debug(

"socket error event ignored during teardown: %O",

errorValue

);

edmundhung · 2026-07-24T15:13:02Z

+	/**
+	 * Tolerate `error` events on the runner WebSocket after the pool worker
+	 * has begun shutting down. Workerd can segfault during teardown on
+	 * linux-x64 / WSL2 and macOS-arm64 (see
+	 * https://github.com/cloudflare/workerd/issues/6763); without this flag,
+	 * those errors reach vitest as fatal `[vitest-pool]: Worker cloudflare-pool
+	 * emitted error`s, failing an otherwise-passing run with exit 1.
+	 *
+	 * Errors raised while a task is in flight are still forwarded normally;
+	 * only post-`stop()` `error` events are suppressed (and logged via
+	 * `NODE_DEBUG=vitest-pool-workers`).
+	 *
+	 * @default false
+	 */
+	tolerateWorkerShutdownErrors: z.boolean().default(false),


There is no need to add an option for this.

trafgals requested a review from workers-devprod as a code owner July 21, 2026 21:57

workers-devprod requested review from a team and petebacondarwin and removed request for a team July 21, 2026 21:57

devin-ai-integration Bot reviewed Jul 21, 2026

View reviewed changes

edmundhung requested review from edmundhung and removed request for petebacondarwin July 24, 2026 10:25

edmundhung requested changes Jul 24, 2026

View reviewed changes

Navigation Menu

Uh oh!

feat(vitest-pool-workers): tolerate post-stop() socket error events when configured - #14794

feat(vitest-pool-workers): tolerate post-stop() socket error events when configured#14794
trafgals wants to merge 1 commit into
cloudflare:mainfrom
trafgals:fix/pool-worker-tolerate-shutdown-socket-errors

trafgals commented Jul 21, 2026 •

edited by devin-ai-integration Bot

Loading

Uh oh!

changeset-bot Bot commented Jul 21, 2026

Uh oh!

workers-devprod commented Jul 21, 2026

Uh oh!

devin-ai-integration Bot left a comment

Uh oh!

devin-ai-integration Bot Jul 21, 2026

Uh oh!

Uh oh!

edmundhung Jul 24, 2026

Uh oh!

edmundhung Jul 24, 2026

Uh oh!

edmundhung Jul 24, 2026

Uh oh!

edmundhung Jul 24, 2026

Uh oh!

edmundhung Jul 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	fix: tolerate post-`stop()` socket `error` events when configured
	Tolerate post-`stop()` socket `error` events when configured

Uh oh!

Conversation

trafgals commented Jul 21, 2026 • edited by devin-ai-integration Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Relationship to #14793

Root-cause recap

Reproduction

Implementation notes

Related

Uh oh!

changeset-bot Bot commented Jul 21, 2026

🦋 Changeset detected

Uh oh!

workers-devprod commented Jul 21, 2026

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

edmundhung Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

edmundhung Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

edmundhung Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

edmundhung Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

edmundhung Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

trafgals commented Jul 21, 2026 •

edited by devin-ai-integration Bot

Loading