{"record":{"id":"79e997e71fd2447a","repo":"can1357/oh-my-pi","slug":"failed-to-install-chromium-for-puppeteer-err-a","errorCode":null,"errorMessage":"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.","messagePattern":"Failed to install Chromium for puppeteer: (.+?)\\. Set PUPPETEER_EXECUTABLE_PATH to use an existing Chrome/Chromium binary, or install one manually\\.","errorType":"exception","errorClass":"ToolError","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/tools/browser/launch.ts","lineNumber":246,"sourceCode":"\t\t\tbrowser: browsers.Browser.CHROME,\n\t\t\tbuildId,\n\t\t\tcacheDir,\n\t\t\tplatform,\n\t\t\tdownloadProgressCallback: ({ downloadedBytes, totalBytes }) => {\n\t\t\t\tif (totalBytes <= 0) return;\n\t\t\t\tconst pct = Math.floor((downloadedBytes / totalBytes) * 100);\n\t\t\t\tif (pct >= lastReportedPercent + 10 || downloadedBytes === totalBytes) {\n\t\t\t\t\tlastReportedPercent = pct;\n\t\t\t\t\tlogger.debug(\n\t\t\t\t\t\t`Chromium download: ${pct}% (${Math.round(downloadedBytes / 1_000_000)} / ${Math.round(totalBytes / 1_000_000)} MB)`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t},\n\t\t});\n\t\treturn executablePath;\n\t})().catch(err => {\n\t\tchromiumExecutablePromise = undefined;\n\t\tthrow new ToolError(\n\t\t\t`Failed to install Chromium for puppeteer: ${(err as Error).message}. ` +\n\t\t\t\t\"Set PUPPETEER_EXECUTABLE_PATH to use an existing Chrome/Chromium binary, or install one manually.\",\n\t\t);\n\t});\n\n\ttry {\n\t\treturn await chromiumExecutablePromise;\n\t} catch (err) {\n\t\tif (!preferManagedChromium) throw err;\n\t\t// Chrome for Testing could not be obtained on macOS; degrade to the\n\t\t// system Chrome bundle rather than leaving the browser tool unusable.\n\t\tconst sysChrome = await resolveSystemChromium();\n\t\tif (!sysChrome) throw err;\n\t\tlogger.warn(\n\t\t\t\"Chrome for Testing unavailable; falling back to the system Chrome bundle. On macOS this can let the \" +\n\t\t\t\t\"headless browser daemon capture your link clicks (#8673). Set PUPPETEER_EXECUTABLE_PATH to a \" +\n\t\t\t\t\"dedicated Chromium to avoid this.\",\n\t\t\t{ path: sysChrome, error: (err as Error).message },","sourceCodeStart":228,"sourceCodeEnd":264,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/tools/browser/launch.ts#L228-L264","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set PUPPETEER_EXECUTABLE_PATH to an existing Chrome/Chromium binary and retry — this short-circuits the download entirely","Install a system Chrome/Chromium (non-macOS picks it up automatically) or pre-install Chrome for Testing into ~/.omp/puppeteer","Fix connectivity/proxy (HTTPS_PROXY) or free disk space, then retry — the failed install promise is reset so the download is reattempted","Check the embedded message for the underlying cause (network vs platform detection vs filesystem) and address it specifically"],"exampleFix":"// before\n// (no env var; download blocked in CI)\n// after\nexport PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser","handlingStrategy":"fallback","validationCode":"const envPath = process.env.PUPPETEER_EXECUTABLE_PATH;\nif (!envPath) {\n  const hasSystemChrome = [\"google-chrome\", \"chromium\", \"chromium-browser\"].some(name =>\n    Bun.which(name));\n  if (!hasSystemChrome) console.warn(\"No Chromium source available; set PUPPETEER_EXECUTABLE_PATH or allow network egress for the first-use download\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  const exe = await ensureChromiumExecutable();\n} catch (err) {\n  if (err instanceof ToolError && err.message.startsWith(\"Failed to install Chromium\")) {\n    // set PUPPETEER_EXECUTABLE_PATH to a local chrome, or fix network/disk, then retry\n  }\n  throw err;\n}","preventionTips":["Set PUPPETEER_EXECUTABLE_PATH in CI/air-gapped/egress-restricted environments before first browser use","Pre-warm the cache (~/.omp/puppeteer) during image build so no runtime download is needed","Ensure HTTPS_PROXY/egress to storage.googleapis.com and writable disk under ~/.omp","Install a system Chrome/Chromium so non-macOS hosts skip the download entirely"],"tags":["chromium","download","network","puppeteer","installation"],"backgroundTag":"chromium-download-failed","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}