{"record":{"id":"4c742fdec15ad83e","repo":"heygen-com/hyperframes","slug":"chromium-chrome-binary-unavailable-source-sou","errorCode":null,"errorMessage":"[chromium] Chrome binary unavailable (source=${source}): @sparticuz/chromium.executablePath() returned a falsy value or a path that doesn't exist on disk. This typically happens after a chunk hits `Sandbox.Timedout` mid-extraction and leaves /tmp in a wedged state — subsequent invocations land on the same warm instance and never re-extract. Recycle the function (e.g. `aws lambda update-function-configuration ... --environment ...` with a bumped marker var, or redeploy via `hyperframes lambda deploy --skip-build`) to force fresh execution environments. Tracking: investigate the upstream wedge so this auto-recovers.","messagePattern":"\\[chromium\\] Chrome binary unavailable \\(source=\\$\\{source\\}\\): @sparticuz/chromium\\.executablePath\\(\\) returned a falsy value or a path that doesn't exist on disk\\. This typically happens after a chunk hits `Sandbox\\.Timedout` mid-extraction and leaves /tmp in a wedged state — subsequent invocations land on the same warm instance and never re-extract\\. Recycle the function \\(e\\.g\\. `aws lambda update-function-configuration \\.\\.\\. --environment \\.\\.\\.` with a bumped marker var, or redeploy via `hyperframes lambda deploy --skip-build`\\) to force fresh execution environments\\. Tracking: investigate the upstream wedge so this auto-recovers\\.","errorType":"exception","errorClass":"ChromeBinaryUnavailableError","httpStatus":null,"severity":"critical","filePath":"packages/aws-lambda/src/chromium.ts","lineNumber":104,"sourceCode":" *\n * For `\"chrome-headless-shell\"`: read the path from\n * `HYPERFRAMES_LAMBDA_CHROME_PATH`. Throws if absent or non-existent so a\n * misconfigured deploy fails loudly at boot rather than at first frame.\n */\n// fallow-ignore-next-line complexity\nexport async function resolveChromeExecutablePath(): Promise<string> {\n  const source = resolveChromeSource();\n  if (source === \"sparticuz\") {\n    const mod = await loadSparticuzChromium();\n    const path = await mod.executablePath();\n    // Guard against the wedge described in ChromeBinaryUnavailableError.\n    // sparticuz's contract is \"return the path to a usable binary\" — when\n    // it returns null/undefined/\"\" we can't hand that to puppeteer-core\n    // (which will throw an unrelated-looking assertion). Same when the\n    // returned path doesn't exist (extraction failed but the function\n    // call returned).\n    if (!path || typeof path !== \"string\") {\n      throw new ChromeBinaryUnavailableError(source, null, SPARTICUZ_WEDGE_HINT);\n    }\n    if (!existsSync(path)) {\n      throw new ChromeBinaryUnavailableError(source, path, SPARTICUZ_WEDGE_HINT);\n    }\n    return path;\n  }\n  const explicit = process.env.HYPERFRAMES_LAMBDA_CHROME_PATH;\n  if (!explicit) {\n    throw new ChromeBinaryUnavailableError(\n      source,\n      null,\n      \"HYPERFRAMES_LAMBDA_CHROME_SOURCE=chrome-headless-shell requires \" +\n        \"HYPERFRAMES_LAMBDA_CHROME_PATH to be set to the absolute path of the bundled binary.\",\n    );\n  }\n  if (!existsSync(explicit)) {\n    throw new ChromeBinaryUnavailableError(\n      source,","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/aws-lambda/src/chromium.ts#L86-L122","documentation":"A `ChromeBinaryUnavailableError` thrown when `@sparticuz/chromium`'s `executablePath()` resolves to a non-string (null/undefined/empty). The resolver refuses to forward a falsy value to puppeteer-core because puppeteer would surface an unrelated-looking assertion instead. The hint points at a known `Sandbox.Timedout` mid-extraction wedge that leaves `/tmp` dirty on warm Lambda instances.","triggerScenarios":"`resolveChromeExecutablePath()` with `HYPERFRAMES_LAMBDA_CHROME_SOURCE=sparticuz` where `mod.executablePath()` returns null/undefined/\"\" — typically because a prior extraction timed out and the warm container never re-extracts.","commonSituations":"Lambda warm instance wedged after a `Sandbox.Timedout` mid-extraction; corrupted/incomplete `/tmp/chromium` extraction from a previous invocation; @sparticuz/chromium version regression that changed `executablePath()` semantics.","solutions":["Recycle the Lambda execution environment: `aws lambda update-function-configuration --function-name <fn> --environment Variables=<existing>,HF_RECYCLE_MARKER=$(date +%s)` to force fresh containers.","Redeploy with `hyperframes lambda deploy --skip-build` to get new instances.","Bump the Lambda timeout / memory so extraction completes before `Sandbox.Timedout`.","Pin or upgrade @sparticuz/chromium to a known-good version for your Lambda node runtime.","Investigate the upstream wedge so warm instances auto-recover (tracking note in the hint)."],"exampleFix":"# before: warm instance wedged\naws lambda invoke --function-name my-fn out.json\n# after: recycle to force re-extraction\naws lambda update-function-configuration --function-name my-fn --environment \"Variables={HF_RECYCLE_MARKER=$(date +%s)}\"","handlingStrategy":"retry","validationCode":null,"typeGuard":"function isUsableChromiumPath(path: unknown): path is string {\n  return typeof path === \"string\" && path.length > 0;\n}","tryCatchPattern":"import { ChromeBinaryUnavailableError } from \"@hyperframes/aws-lambda\";\ntry {\n  const p = await resolveChromeExecutablePath();\n} catch (err) {\n  if (err instanceof ChromeBinaryUnavailableError && err.source === \"sparticuz\") {\n    // recycle the environment via update-function-configuration / redeploy, then retry\n  }\n  throw err;\n}","preventionTips":["Run the BeginFrame probe in CI on the same Lambda image to catch sparticuz regressions before deploy.","Pin @sparticuz/chromium to a known-good version and update deliberately.","Add a startup health check that calls executablePath() on cold start and recycles on failure.","Alert on ChromeBinaryUnavailableError in CloudWatch and auto-trigger a recycle."],"tags":["chromium","lambda","sparticuz","runtime-environment","browser"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}