[miniflare] Recover from corrupted @puppeteer/browsers cache in launchBrowser (#13980)

petebacondarwin · web-flow · commit e8c2031b9ad7 · 2026-05-20T10:29:31.000Z
diff --git a/.changeset/miniflare-recover-from-corrupted-chrome-cache.md b/.changeset/miniflare-recover-from-corrupted-chrome-cache.md
@@ -0,0 +1,11 @@
+---
+"miniflare": patch
+---
+
+Recover from corrupted `@puppeteer/browsers` cache when launching a Browser Run session
+
+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 `The browser folder (...) exists but the executable (...) is missing` on every subsequent call within the same process and the entire test session, breaking every later Browser Run operation until the cache is manually cleared.
+
+`launchBrowser` now catches that specific error, removes the corrupted cache directory, and retries `install()` once. If the corruption persists after cleanup, the original error is rethrown with a clearer message.
+
+This complements [#13971](https://github.com/cloudflare/workers-sdk/pull/13971), which surfaced the original error from inside the binding worker. With that diagnostic in place and this self-healing layer, the previously-intermittent "browser folder exists but executable missing" failure mode should no longer fail an entire CI run.
diff --git a/packages/miniflare/src/plugins/browser-rendering/index.ts b/packages/miniflare/src/plugins/browser-rendering/index.ts
@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { brandColor } from "@cloudflare/cli-shared-helpers/colors";
+import { brandColor, dim, red } from "@cloudflare/cli-shared-helpers/colors";
 import { spinner } from "@cloudflare/cli-shared-helpers/interactive";
 import { removeDir } from "@cloudflare/workers-utils";
 import {
@@ -11,7 +11,6 @@ import {
 	launch,
 	resolveBuildId,
 } from "@puppeteer/browsers";
-import { dim } from "kleur/colors";
 import BROWSER_RENDERING_WORKER from "worker:browser-rendering/binding";
 import { z } from "zod";
 import { kVoid } from "../../runtime";
@@ -24,6 +23,7 @@ import {
 } from "../shared";
 import type { Log } from "../../shared";
 import type { Plugin, RemoteProxyConnectionString } from "../shared";
+import type { InstalledBrowser, InstallOptions } from "@puppeteer/browsers";
 
 const BrowserRenderingSchema = z.object({
 	binding: z.string(),
@@ -138,20 +138,33 @@ export async function launchBrowser({
 	const s = spinner();
 	let startedDownloading = false;
 
-	const { executablePath } = await install({
+	const installOptions = {
 		browser,
 		platform,
 		cacheDir: getGlobalWranglerCachePath(),
 		buildId: await resolveBuildId(browser, platform, browserVersion),
-		downloadProgressCallback: (downloadedBytes, totalBytes) => {
+		downloadProgressCallback: (downloadedBytes: number, totalBytes: number) => {
 			if (!startedDownloading) {
 				s.start(`Downloading browser...`);
 				startedDownloading = true;
 			}
 			const progress = Math.round((downloadedBytes / totalBytes) * 100);
 			s.update(`Downloading browser... ${progress}%`);
 		},
-	});
+	};
+
+	let executablePath: string;
+	try {
+		({ executablePath } = await installWithCorruptedCacheRecovery(
+			installOptions,
+			log
+		));
+	} catch (e) {
+		if (startedDownloading) {
+			s.stop(`${red("failed")} ${dim(`browser download`)}`);
+		}
+		throw e;
+	}
 
 	if (startedDownloading) {
 		s.stop(`${brandColor("downloaded")} ${dim(`browser`)}`);
@@ -238,6 +251,64 @@ export async function launchBrowser({
 	return { sessionId, browserProcess, startTime, wsEndpoint };
 }
 
+/**
+ * Regex matching the `@puppeteer/browsers` error thrown when its cache
+ * directory exists but the executable inside it is missing — typically
+ * because a previous `install()` was interrupted mid-extraction (test
+ * timeout, process kill) or because an external agent (Windows Defender,
+ * antivirus, disk cleanup) removed the executable from a previously-good
+ * install.
+ *
+ * @puppeteer/browsers source:
+ * https://github.com/puppeteer/puppeteer/blob/main/packages/browsers/src/install.ts
+ */
+const CORRUPTED_CACHE_ERROR_PATTERN =
+	/The browser folder \((.+?)\) exists but the executable .+? is missing/;
+
+/**
+ * Run `@puppeteer/browsers` `install()`, but if it fails with the
+ * "folder exists but executable is missing" error, clear the corrupted
+ * cache directory and retry once.
+ *
+ * Recovers from a known intermittent failure on CI runners (especially
+ * Windows) where the cache state can become partially populated and stay
+ * that way for the rest of the run, breaking every subsequent test until
+ * the runner is recycled.
+ */
+async function installWithCorruptedCacheRecovery(
+	installOptions: InstallOptions & { unpack?: true },
+	log: Log
+): Promise<InstalledBrowser> {
+	try {
+		return await install(installOptions);
+	} catch (e) {
+		const match = (e as Error)?.message?.match(CORRUPTED_CACHE_ERROR_PATTERN);
+		if (!match) {
+			throw e;
+		}
+		const corruptedPath = match[1];
+		log.warn(
+			`Detected corrupted Chrome cache at ${corruptedPath}; clearing and retrying install.`
+		);
+		try {
+			await removeDir(corruptedPath);
+		} catch (cleanupError) {
+			throw new Error(
+				`Failed to clear corrupted Chrome cache at ${corruptedPath} after detecting "${(e as Error).message}". Manual cleanup may be required.`,
+				{ cause: cleanupError }
+			);
+		}
+		try {
+			return await install(installOptions);
+		} catch (retryError) {
+			throw new Error(
+				`Chrome install failed after clearing corrupted cache at ${corruptedPath}: ${(retryError as Error).message}`,
+				{ cause: retryError }
+			);
+		}
+	}
+}
+
 /**
  * Probe Chrome's HTTP DevTools endpoint until it accepts connections.
  *
