[miniflare] Recover from corrupted @puppeteer/browsers cache in launchBrowser

[petebacondarwin]

No tracked issue; follow-up to #13971.

What

When Miniflare's local Browser Run binding launches Chrome, it calls @puppeteer/browsers' install() to ensure the binary is present. If a previous install() was interrupted mid-extraction (test timeout, process kill, antivirus quarantine), the cache directory can be left partially populated — the folder exists but the executable inside it is missing. install() then throws on every subsequent call within the same process for the rest of the test session:

Error: The browser folder (C:\Users\runneradmin\AppData\Local\xdg.cache\.wrangler\chrome\win64-126.0.6478.182) exists but the executable (...\chrome.exe) is missing
    at installUrl (...@puppeteer/browsers/src/install.ts:309:15)
    at install (...@puppeteer/browsers/src/install.ts:157:18)
    at launchBrowser (.../packages/miniflare/src/plugins/browser-rendering/index.ts:141:35)

This was visible on a previous CI run for #13971 (job log) and recurs intermittently on Windows runners. With retry: 3 configured on the affected tests, all four attempts hit the same corrupted state and all four fail.

How

Wrap the install() call in launchBrowser with installWithCorruptedCacheRecovery, which:

1. Calls install(options).
2. If it throws and the message matches /The browser folder \((.+?)\) exists but the executable .+? is missing/, captures the corrupted path.
3. Logs a warning, removeDirs the corrupted path, retries install() once.
4. If cleanup itself fails, rethrows with a clear message asking for manual intervention.
5. Any other install error rethrows unchanged.

The regex is matched against the literal error string from @puppeteer/browsers@2.10.6/src/install.ts:309-311. If @puppeteer/browsers ever rewords that error, this branch becomes a no-op (we'd rethrow the original error, just without recovery) — no risk of silently swallowing unrelated install failures.

Test plan

• pnpm -F miniflare check:type ✅
• pnpm check:lint ✅
• pnpm check:format ✅
• pnpm -F miniflare test:ci test/plugins/browser/index.spec.ts ✅ — all 21 browser tests pass on the happy path
• Manual recovery verification: deleted the chrome executable from the local wrangler cache (~/Library/Caches/.wrangler/chrome/mac_arm-126.0.6478.182/.../Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing), then ran pnpm -F miniflare test:ci test/plugins/browser/index.spec.ts -t "it creates a browser session". The test passed — the install error was detected, the cache directory was cleared, and Chrome was re-downloaded on the retry.

Why no new tests

The recovery path is only hit when an external system (filesystem state, antivirus, OS) puts the cache into an invalid state. Writing a unit test that synthetically corrupts the cache would either (a) duplicate the @puppeteer/browsers state machine in mock code, or (b) actually invoke the real install() against a real cache, which makes it slow and flaky. The manual verification above exercises the real flow against a real corrupted cache, which is what we care about.

---

• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows: deleted the chrome executable from the local wrangler cache, ran pnpm -F miniflare test:ci test/plugins/browser/index.spec.ts -t "it creates a browser session", confirmed the install error was detected, the cache directory was cleared, and Chrome was re-downloaded. See "Test plan" above.
  • Additional testing not necessary because:
• Public documentation
  • Cloudflare docs PR(s):
  • Documentation not necessary because: internal recovery for a Miniflare-internal @puppeteer/browsers cache failure mode. No public API or user-facing behaviour change beyond a more helpful warning log when the recovery fires.

---

[changeset-bot]

🦋 Changeset detected

Latest commit: c5c1999

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

This PR includes changesets to release 5 packages

Name	Type
miniflare	Patch
@cloudflare/pages-shared	Patch
@cloudflare/vite-plugin	Patch
@cloudflare/vitest-pool-workers	Patch
wrangler	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]

Codeowners approval required for this PR:

• ✅ @cloudflare/wrangler

Show detailed file reviewers

[github-actions]

✅ All changesets look good

[ask-bonk]

Now I have a full picture. Let me verify the type signature. The install function has overloads:

export function install(options: InstallOptions & {unpack?: true}): Promise<InstalledBrowser>;
export function install(options: InstallOptions & {unpack: false}): Promise<string>;

The wrapper function signature InstallOptions & { unpack?: true } correctly matches the first overload that returns Promise<InstalledBrowser>. Good.

Now let me verify the error message in the source matches the regex:

The error in @puppeteer/browsers is:

`The browser folder (${outputPath}) exists but the executable (${installedBrowser.executablePath}) is missing`

The regex is:

/The browser folder \((.+?)\) exists but the executable .+? is missing/

This correctly captures outputPath (the corrupted folder path) in group 1. The regex uses non-greedy .+? which is appropriate here.

Let me also verify that the error path captured (outputPath) is the correct directory to remove. Looking at the @puppeteer/browsers source, outputPath = cache.installationDir(...) and the check is if (existsSync(outputPath)) — so outputPath is the installation directory. Removing it would allow install() to re-download and re-extract, which is exactly what we want.

One thing I notice: the downloadProgressCallback parameter typing was changed from inferred to explicit (downloadedBytes: number, totalBytes: number). Looking at the upstream InstallOptions, the downloadProgressCallback type is:

downloadProgressCallback?: 'default' | ((downloadedBytes: number, totalBytes: number) => void);

The explicit annotations on the callback parameters are fine — they were likely needed because extracting the options object into a separate variable lost the contextual typing from install()'s parameter type. This is correct.

Let me also check for any potential issues with the removeDir call — specifically, whether it could accidentally remove something it shouldn't if the regex match is somehow wrong:

The regex captures the path between ( and ) in The browser folder (<path>) exists.... This path comes directly from @puppeteer/browsers's outputPath which is cache.installationDir(browser, platform, buildId) — a subdirectory under the cache dir. So it's safe to remove.

Let me also verify the error thrown in the cleanup failure case preserves the original error information:

throw new Error(
    `Failed to clear corrupted Chrome cache at ${corruptedPath} after detecting "${(e as Error).message}". Manual cleanup may be required.`,
    { cause: cleanupError }
);

This preserves the cleanup error as cause and includes the original error message in the text. However, it does not preserve the original error e as a cause — the cause is only the cleanupError. The original install error message is embedded in the string, but the original error object (with its stack trace) is lost.

Actually, looking more carefully — this is a minor concern. The original error message is fully quoted in the new error message string, which is sufficient for diagnostics. The cause is the cleanup error, which is the more actionable piece (why cleanup failed). This is reasonable.

Overall this is a clean, well-scoped change. The logic is sound, the recovery is single-retry (no infinite loops), non-matching errors pass through unchanged, and the regex degradation mode (if @puppeteer/browsers changes the error message) is a safe no-op.

LGTM

github run

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.

[pkg-pr-new]

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@13980

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@13980

miniflare

npm i https://pkg.pr.new/miniflare@13980

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@13980

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@13980

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@13980

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@13980

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@13980

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@13980

wrangler

npm i https://pkg.pr.new/wrangler@13980

commit: c5c1999

[workers-devprod]

Codeowners reviews satisfied