can1357/oh-my-pi · error · ToolError

Failed to install Chromium for puppeteer: ${(err as Error).m

Error message

Failed to install Chromium for puppeteer: ${(err as Error).message}. Set PUPPETEER_EXECUTABLE_PATH to use an existing Chrome/Chromium binary, or install one manually.

What it means

ensureChromiumExecutable() resolves a Chromium binary: PUPPETEER_EXECUTABLE_PATH wins, else a system Chrome (non-macOS), else it downloads Chrome for Testing into the managed cache (~/.omp/puppeteer) via @puppeteer/browsers install(). If that detect/resolve/install pipeline fails (network failure, unsupported platform, disk error, revision resolution failure), the promise rejects and the error is rewrapped in this ToolError with remediation guidance. On macOS a subsequent fallback to system Chrome may still save the call; elsewhere it propagates.

Source

Thrown at packages/coding-agent/src/tools/browser/launch.ts:246

			browser: browsers.Browser.CHROME,
			buildId,
			cacheDir,
			platform,
			downloadProgressCallback: ({ downloadedBytes, totalBytes }) => {
				if (totalBytes <= 0) return;
				const pct = Math.floor((downloadedBytes / totalBytes) * 100);
				if (pct >= lastReportedPercent + 10 || downloadedBytes === totalBytes) {
					lastReportedPercent = pct;
					logger.debug(
						`Chromium download: ${pct}% (${Math.round(downloadedBytes / 1_000_000)} / ${Math.round(totalBytes / 1_000_000)} MB)`,
					);
				}
			},
		});
		return executablePath;
	})().catch(err => {
		chromiumExecutablePromise = undefined;
		throw new ToolError(
			`Failed to install Chromium for puppeteer: ${(err as Error).message}. ` +
				"Set PUPPETEER_EXECUTABLE_PATH to use an existing Chrome/Chromium binary, or install one manually.",
		);
	});

	try {
		return await chromiumExecutablePromise;
	} catch (err) {
		if (!preferManagedChromium) throw err;
		// Chrome for Testing could not be obtained on macOS; degrade to the
		// system Chrome bundle rather than leaving the browser tool unusable.
		const sysChrome = await resolveSystemChromium();
		if (!sysChrome) throw err;
		logger.warn(
			"Chrome for Testing unavailable; falling back to the system Chrome bundle. On macOS this can let the " +
				"headless browser daemon capture your link clicks (#8673). Set PUPPETEER_EXECUTABLE_PATH to a " +
				"dedicated Chromium to avoid this.",
			{ path: sysChrome, error: (err as Error).message },

View on GitHub (pinned to 9690622007)

Solutions

1. Set PUPPETEER_EXECUTABLE_PATH to an existing Chrome/Chromium binary and retry — this short-circuits the download entirely
2. Install a system Chrome/Chromium (non-macOS picks it up automatically) or pre-install Chrome for Testing into ~/.omp/puppeteer
3. Fix connectivity/proxy (HTTPS_PROXY) or free disk space, then retry — the failed install promise is reset so the download is reattempted
4. Check the embedded message for the underlying cause (network vs platform detection vs filesystem) and address it specifically

Example fix

// before
// (no env var; download blocked in CI)
// after
export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

const envPath = process.env.PUPPETEER_EXECUTABLE_PATH;
if (!envPath) {
  const hasSystemChrome = ["google-chrome", "chromium", "chromium-browser"].some(name =>
    Bun.which(name));
  if (!hasSystemChrome) console.warn("No Chromium source available; set PUPPETEER_EXECUTABLE_PATH or allow network egress for the first-use download");
}

try {
  const exe = await ensureChromiumExecutable();
} catch (err) {
  if (err instanceof ToolError && err.message.startsWith("Failed to install Chromium")) {
    // set PUPPETEER_EXECUTABLE_PATH to a local chrome, or fix network/disk, then retry
  }
  throw err;
}

When it happens

Trigger: No network / blocked download host when installing Chrome for Testing; detectBrowserPlatform() or resolveBuildId() failing for an exotic platform; corrupted or unwritable ~/.omp/puppeteer cache dir; PUPPETEER_REVISIONS lookup failing in a mismatched puppeteer-core install.

Common situations: CI containers/sandboxes with egress restrictions; air-gapped machines; full disks; corporate proxies blocking storage.googleapis.com; first browser use on a new machine with no cached Chromium and no system Chrome.

Related errors

• Failed to download the local text-to-speech model.
• One or more tiny title models failed to download
• Timed out downloading release binary after 15 minutes
• Download failed: ${response.statusText}
• Downloaded binary size mismatch: expected ${options.expected

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/79e997e71fd2447a. Report an issue: GitHub.