{"record":{"id":"5a1a36db6cf6a6bf","repo":"heygen-com/hyperframes","slug":"browsermanager-chrome-binary-not-found-at-hyperf","errorCode":null,"errorMessage":"[BrowserManager] Chrome binary not found at HYPERFRAMES_BROWSER_PATH=\"${envPath}\". Run `hyperframes browser ensure` to re-download.","messagePattern":"\\[BrowserManager\\] Chrome binary not found at HYPERFRAMES_BROWSER_PATH=\"(.+?)\"\\. Run `hyperframes browser ensure` to re-download\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/engine/src/services/browserManager.ts","lineNumber":199,"sourceCode":"  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 (\n    findCachedHeadlessShell(\n      join(home, \".cache\", \"hyperframes\", \"chrome\", \"chrome-headless-shell\"),\n    ) ?? findCachedHeadlessShell(join(home, \".cache\", \"puppeteer\", \"chrome-headless-shell\"))\n  );\n}\n\n// Preserve the producer-era export so re-export shims keep the same public API.\nexport const ENABLE_BROWSER_POOL = DEFAULT_CONFIG.enableBrowserPool;\n\n// Flags only meaningful when Chrome's compositor is driven by","sourceCodeStart":181,"sourceCodeEnd":217,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/engine/src/services/browserManager.ts#L181-L217","documentation":"Thrown by resolveHeadlessShellPath() when the HYPERFRAMES_BROWSER_PATH environment variable is set to a path that does not exist on disk. This is the third priority in the resolution chain (after config.chromePath and PRODUCER_HEADLESS_SHELL_PATH). Like the other env-var checks, a set-but-missing path throws rather than silently falling through, because an explicit override should be respected or corrected.","triggerScenarios":"resolveHeadlessShellPath() reaches the HYPERFRAMES_BROWSER_PATH branch (config.chromePath is unset, PRODUCER_HEADLESS_SHELL_PATH is unset or resolved already). The env var is non-empty, existsSync fails on its value, and the error fires.","commonSituations":"HYPERFRAMES_BROWSER_PATH was set for a local dev machine but the project was moved or Chrome was updated/removed. CI inherited the env var from a different runner image. A teammate's shell profile exports it globally.","solutions":["Run hyperframes browser ensure to re-download the managed Chrome headless shell.","Verify or unset: ls -la $HYPERFRAMES_BROWSER_PATH or unset HYPERFRAMES_BROWSER_PATH.","If you intentionally set this for a system Chrome install, reinstall Chrome or update the path.","Use config.chromePath in code/config instead of env vars for reproducible team setups."],"exampleFix":"# before\nexport HYPERFRAMES_BROWSER_PATH=/usr/bin/google-chrome\n# (Chrome uninstalled)\n\n# after\nnpx hyperframes browser ensure\n# or unset HYPERFRAMES_BROWSER_PATH","handlingStrategy":"validation","validationCode":"import { existsSync } from 'fs';\n\nfunction validateBrowserPath(): void {\n  const envPath = process.env.HYPERFRAMES_BROWSER_PATH;\n  if (envPath && !existsSync(envPath)) {\n    console.warn(`HYPERFRAMES_BROWSER_PATH points to missing file: ${envPath}. Unsetting.`);\n    delete process.env.HYPERFRAMES_BROWSER_PATH;\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  resolveHeadlessShellPath(config);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('HYPERFRAMES_BROWSER_PATH')) {\n    delete process.env.HYPERFRAMES_BROWSER_PATH;\n    resolveHeadlessShellPath(config);\n  }\n  throw err;\n}","preventionTips":["Validate env-var paths at application startup.","Use hyperframes browser ensure to manage the Chrome cache instead of manual env-var paths.","Document which env vars take priority so team members don't set conflicting values."],"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"}