Cached Chrome binary was missing at ${fromCache.staleHyperfr

Error message

Cached Chrome binary was missing at ${fromCache.staleHyperframesCachePath}, and re-download failed: ${cause}\nRun `hyperframes browser ensure --force` to re-download.

What it means

Thrown by findBrowser() when a cached chrome-headless-shell binary was expected at the hyperframes cache path but is missing (staleHyperframesCachePath set), AND the re-download attempt inside withInstallLock also failed. The message names the stale cache path and the download failure cause, and points the user to `hyperframes browser ensure --force` to re-download cleanly.

Source

Thrown at packages/cli/src/browser/manager.ts:511

 */
export async function findBrowser(): Promise<BrowserResult | undefined> {
  const fromEnv = findFromEnv();
  if (fromEnv) return fromEnv;

  const fromCache = await findFromCache();
  if (fromCache.result) return fromCache.result;
  if (fromCache.staleHyperframesCachePath) {
    console.warn(
      `[browser] Cached binary missing at ${fromCache.staleHyperframesCachePath} — re-downloading...`,
    );
    try {
      return await withInstallLock(async () => {
        if (fromCache.staleInstallPath) purgeStaleInstall(fromCache.staleInstallPath);
        return downloadBrowser();
      });
    } catch (err) {
      const cause = normalizeErrorMessage(err);
      throw new Error(
        `Cached Chrome binary was missing at ${fromCache.staleHyperframesCachePath}, and re-download failed: ${cause}\n` +
          `Run \`hyperframes browser ensure --force\` to re-download.`,
      );
    }
  }

  const fromSystem = findFromSystem();
  if (fromSystem) {
    warnSystemFallbackOnce(fromSystem.executablePath);
  }
  return fromSystem;
}

/**
 * On Linux ARM64, attempt to auto-install system Chromium if not found.
 * This makes `hyperframes render` work out-of-the-box on DGX Spark / GB10 / Jetson.
 */
async function ensureLinuxArmBrowser(options?: EnsureBrowserOptions): Promise<BrowserResult> {

View on GitHub (pinned to c2996c8626)

Solutions

Run `hyperframes browser ensure --force` to purge and re-download the chrome-headless-shell binary.
Check the underlying cause in the message — fix network/proxy/disk issues that blocked the download.
If re-download keeps failing, point hyperframes at a system Chrome via HYPERFRAMES_BROWSER_PATH as a fallback.

Example fix

# before — stale cache + download failed
$ hyperframes render ...
# force re-download
$ hyperframes browser ensure --force
$ hyperframes render ...
# fallback: use system Chrome
$ export HYPERFRAMES_BROWSER_PATH=$(which google-chrome)
$ hyperframes render ...

Defensive patterns

Strategy: fallback

Try / catch

try {
  await ensureBrowser();
} catch (err) {
  const msg = (err as Error).message;
  if (/Cached Chrome binary was missing/.test(msg)) {
    // fallback: point at system Chrome
    process.env.HYPERFRAMES_BROWSER_PATH = '/usr/bin/google-chrome';
    await ensureBrowser();
  } else throw err;
}

Prevention

Run `hyperframes browser ensure --force` after cache issues instead of retrying blindly.
Set HYPERFRAMES_BROWSER_PATH to a system Chrome as a reliable fallback in CI.
Avoid manually deleting parts of ~/.cache/hyperframes/chrome.

When it happens

Trigger: findBrowser() → findFromCache() returns a stale path (cache metadata present, binary absent); withInstallLock(downloadBrowser) rejects due to network failure, disk full, or a corrupt archive; the combined error is raised.

Common situations: User manually deleted part of ~/.cache/hyperframes/chrome; a previous download was interrupted leaving partial state; network/proxy blocks the chrome-headless-shell CDN; disk full in the cache directory; a corrupt archive that the recovery logic couldn't fix.

Related errors

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/a36d6d37382c384d. Report an issue: GitHub.