{"record":{"id":"bdea255b5217cf1d","repo":"heygen-com/hyperframes","slug":"chromium-chrome-binary-unavailable-source-sou-bdea25","errorCode":null,"errorMessage":"[chromium] Chrome binary unavailable (source=${source}): HYPERFRAMES_LAMBDA_CHROME_SOURCE=chrome-headless-shell requires HYPERFRAMES_LAMBDA_CHROME_PATH to be set to the absolute path of the bundled binary.","messagePattern":"\\[chromium\\] Chrome binary unavailable \\(source=(.+?)\\): HYPERFRAMES_LAMBDA_CHROME_SOURCE=chrome-headless-shell requires HYPERFRAMES_LAMBDA_CHROME_PATH to be set to the absolute path of the bundled binary\\.","errorType":"exception","errorClass":"ChromeBinaryUnavailableError","httpStatus":null,"severity":"critical","filePath":"packages/aws-lambda/src/chromium.ts","lineNumber":113,"sourceCode":"    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,\n      explicit,\n      `HYPERFRAMES_LAMBDA_CHROME_PATH=${JSON.stringify(explicit)} does not exist on disk.`,\n    );\n  }\n  return explicit;\n}\n\n/**\n * Resolve the Chromium launch args for the selected source. For","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/aws-lambda/src/chromium.ts#L95-L131","documentation":"A `ChromeBinaryUnavailableError` thrown when the source is `chrome-headless-shell` (explicit fallback) but `HYPERFRAMES_LAMBDA_CHROME_PATH` is unset. The fallback resolver does not search PATH — it requires the operator to point at the bundled binary's absolute path because build-zip places it at a known location only when configured.","triggerScenarios":"`resolveChromeExecutablePath()` with `HYPERFRAMES_LAMBDA_CHROME_SOURCE=chrome-headless-shell` and `process.env.HYPERFRAMES_LAMBDA_CHROME_PATH` falsy — i.e. the deploy set the source discriminator without wiring the path, or a SAM-local run forgot the override.","commonSituations":"Misconfigured deploy that set `HYPERFRAMES_LAMBDA_CHROME_SOURCE` to the fallback without bundling the binary or setting its path; SAM-local RIE smoke run missing the env override; build-zip.ts change that stopped emitting the path env var.","solutions":["Set HYPERFRAMES_LAMBDA_CHROME_PATH to the absolute path of the bundled chrome-headless-shell binary inside the Lambda zip.","Or switch back to the sparticuz source: `HYPERFRAMES_LAMBDA_CHROME_SOURCE=sparticuz`.","Verify build-zip.ts actually bundles the binary at the configured path.","For SAM-local, pass the env var through template.yaml / event overrides."],"exampleFix":"# before\nHYPERFRAMES_LAMBDA_CHROME_SOURCE=chrome-headless-shell\n# after\nHYPERFRAMES_LAMBDA_CHROME_SOURCE=chrome-headless-shell\nHYPERFRAMES_LAMBDA_CHROME_PATH=/var/task/bin/chrome-headless-shell","handlingStrategy":"validation","validationCode":"function assertChromeConfigured(): void {\n  const source = process.env.HYPERFRAMES_LAMBDA_CHROME_SOURCE;\n  if (source === \"chrome-headless-shell\" && !process.env.HYPERFRAMES_LAMBDA_CHROME_PATH) {\n    throw new Error(\"HYPERFRAMES_LAMBDA_CHROME_PATH required for chrome-headless-shell source\");\n  }\n}\n// call at cold start","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Add a deploy-time assertion that both env vars are set together when using the shell source.","Document the chrome-headless-shell fallback requirements in the deploy runbook.","Default to the sparticuz source unless you have a reason to bundle the shell binary.","Smoke-test the SAM-local run with the same env shape as production."],"tags":["chromium","lambda","configuration","env","browser"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}