{"record":{"id":"91c1f47af8df016d","repo":"heygen-com/hyperframes","slug":"browsermanager-chrome-binary-not-found-at-produc","errorCode":null,"errorMessage":"[BrowserManager] Chrome binary not found at PRODUCER_HEADLESS_SHELL_PATH=\"${envPath}\". Run `hyperframes browser ensure` to re-download.","messagePattern":"\\[BrowserManager\\] Chrome binary not found at PRODUCER_HEADLESS_SHELL_PATH=\"(.+?)\"\\. Run `hyperframes browser ensure` to re-download\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/engine/src/services/browserManager.ts","lineNumber":189,"sourceCode":"  }\n  return undefined;\n}\n\n/**\n * Resolve chrome-headless-shell binary for deterministic BeginFrame rendering.\n * Checks config.chromePath, then PRODUCER_HEADLESS_SHELL_PATH env var,\n * then the CLI browser override, HyperFrames' managed cache, and Puppeteer's cache.\n */\nexport function resolveHeadlessShellPath(\n  config?: Partial<Pick<EngineConfig, \"chromePath\">>,\n): string | undefined {\n  if (config?.chromePath) {\n    return config.chromePath;\n  }\n  if (process.env.PRODUCER_HEADLESS_SHELL_PATH) {\n    const envPath = process.env.PRODUCER_HEADLESS_SHELL_PATH;\n    if (!existsSync(envPath)) {\n      throw new Error(\n        `[BrowserManager] Chrome binary not found at PRODUCER_HEADLESS_SHELL_PATH=\"${envPath}\". ` +\n          \"Run `hyperframes browser ensure` to re-download.\",\n      );\n    }\n    return envPath;\n  }\n  if (process.env.HYPERFRAMES_BROWSER_PATH) {\n    const envPath = process.env.HYPERFRAMES_BROWSER_PATH;\n    if (!existsSync(envPath)) {\n      throw new Error(\n        `[BrowserManager] Chrome binary not found at HYPERFRAMES_BROWSER_PATH=\"${envPath}\". ` +\n          \"Run `hyperframes browser ensure` to re-download.\",\n      );\n    }\n    return envPath;\n  }\n  const home = homedir();\n  return (","sourceCodeStart":171,"sourceCodeEnd":207,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/engine/src/services/browserManager.ts#L171-L207","documentation":"Thrown by resolveHeadlessShellPath() when the PRODUCER_HEADLESS_SHELL_PATH environment variable is set to a path that does not exist on disk (existsSync returns false). This env var is the second-highest priority in the Chrome binary resolution chain (after config.chromePath), so it explicitly overrides all other lookup paths — a stale value here prevents fallback.","triggerScenarios":"resolveHeadlessShellPath() is called during browser launch. The env var is set (non-empty string), so the code enters the env-check branch and calls existsSync(envPath). If the file was deleted, the path points to a different machine's layout, or the path is a stale Docker layer reference, the check fails.","commonSituations":"Docker/container image was rebuilt and the Chrome binary moved. The env var was set in CI config pointing to a path that only exists in a different image. Chrome was uninstalled or the cache was cleared. The path has a typo or uses a non-absolute relative path that resolves differently at runtime.","solutions":["Run hyperframes browser ensure to re-download the managed Chrome headless shell.","Verify the path exists: ls -la $PRODUCER_HEADLESS_SHELL_PATH — fix or remove the env var if stale.","If the env var is no longer needed, unset it to let resolution fall through to the managed cache or Puppeteer's cache.","In Docker, ensure the Chrome binary is installed in the image at the path the env var declares."],"exampleFix":"# before (stale env var)\nexport PRODUCER_HEADLESS_SHELL_PATH=/opt/chrome/chrome-headless-shell\n# (file deleted after image rebuild)\n\n# after (re-download or unset)\nnpx hyperframes browser ensure\n# or: unset PRODUCER_HEADLESS_SHELL_PATH to fall through to cache","handlingStrategy":"validation","validationCode":"import { existsSync } from 'fs';\n\nfunction validateChromePath(): string | undefined {\n  const envPath = process.env.PRODUCER_HEADLESS_SHELL_PATH;\n  if (envPath && !existsSync(envPath)) {\n    console.warn(`PRODUCER_HEADLESS_SHELL_PATH points to missing file: ${envPath}. Unsetting.`);\n    delete process.env.PRODUCER_HEADLESS_SHELL_PATH;\n  }\n  return envPath && existsSync(envPath) ? envPath : undefined;\n}","typeGuard":null,"tryCatchPattern":"try {\n  resolveHeadlessShellPath(config);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('PRODUCER_HEADLESS_SHELL_PATH')) {\n    // unset the stale env var and retry resolution\n    delete process.env.PRODUCER_HEADLESS_SHELL_PATH;\n    resolveHeadlessShellPath(config);\n  }\n  throw err;\n}","preventionTips":["Run hyperframes browser ensure in setup scripts and CI to pre-populate the managed cache.","Validate env-var paths at startup and warn if stale rather than failing at render time.","Prefer config.chromePath over env vars for team reproducibility."],"tags":["browser","chrome","environment","config","filesystem"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}