heygen-com/hyperframes · critical

Unsupported platform: ${process.platform} ${process.arch}

Error message

Unsupported platform: ${process.platform} ${process.arch}

What it means

Thrown by downloadBrowser() when @puppeteer/browsers's detectBrowserPlatform() returns null, meaning the current OS/arch combination is not recognized as one of the supported puppeteer platforms. This is the fallback after the isLinuxArm() branch (which handles ARM Linux separately), so it fires on x86 Linux, macOS, or Windows variants that puppeteer does not catalog, or on exotic platforms (freebsd, solaris). The message reports process.platform and process.arch for diagnostics.

Source

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

    `Point hyperframes at an already-installed Chrome/Chromium instead:\n\n` +
    `  export HYPERFRAMES_BROWSER_PATH="${example}"\n\n` +
    `Then re-run your command. Any Chrome build works for the screenshot ` +
    `capture path; install a real chrome-headless-shell later if you need the ` +
    `perf-optimized BeginFrame path. Alternatively, run inside the hyperframes ` +
    `Docker image which ships a compatible headless-shell.`;
  return new Error(message, { cause: cause instanceof Error ? cause : undefined });
}

async function downloadBrowser(options?: EnsureBrowserOptions): Promise<BrowserResult> {
  if (isLinuxArm()) {
    return ensureLinuxArmBrowser(options);
  }

  const { Browser, detectBrowserPlatform, install } = await loadPuppeteerBrowsers();

  const platform = detectBrowserPlatform();
  if (!platform) {
    throw new Error(`Unsupported platform: ${process.platform} ${process.arch}`);
  }

  const runInstall = () =>
    install({
      cacheDir: CACHE_DIR,
      browser: Browser.CHROMEHEADLESSSHELL,
      buildId: CHROME_VERSION,
      platform,
      downloadProgressCallback: options?.onProgress,
    });

  let installed;
  try {
    installed = await installWithCorruptArchiveRecovery(
      runInstall,
      () => {
        rmSync(CACHE_DIR, { recursive: true, force: true });
        mkdirSync(CACHE_DIR, { recursive: true });

View on GitHub (pinned to c2996c8626)

Solutions

1. Set HYPERFRAMES_BROWSER_PATH to an already-installed Chrome/Chromium on the host so download is skipped entirely.
2. Run inside the official hyperframes Docker image, which ships a compatible browser.
3. If you believe the platform should be supported, update @puppeteer/browsers (`bun install` to pick up the pinned version) and retry.

Example fix

# before — unsupported platform
$ hyperframes render ...
Error: Unsupported platform: freebsd x64
# point at a system Chromium
$ export HYPERFRAMES_BROWSER_PATH=/usr/local/bin/chromium
$ hyperframes render ...

import { existsSync } from 'node:fs';
function browserPathReady(): boolean {
  return Boolean(process.env.HYPERFRAMES_BROWSER_PATH) && existsSync(process.env.HYPERFRAMES_BROWSER_PATH);
}
if (!browserPathReady() && !['darwin','linux','win32'].includes(process.platform)) {
  throw new Error(`Unsupported platform ${process.platform}/${process.arch}; set HYPERFRAMES_BROWSER_PATH.`);
}

function platformSupported(): boolean {
  return ['darwin','linux','win32'].includes(process.platform);
}

try {
  await ensureBrowser();
} catch (err) {
  if (/Unsupported platform/i.test((err as Error).message)) {
    // set HYPERFRAMES_BROWSER_PATH to a system browser and retry
  }
  throw err;
}

When it happens

Trigger: downloadBrowser() is called on a platform where detectBrowserPlatform() returns null — e.g. FreeBSD, Solaris, or an exotic arch; rarely on standard darwin/linux/win32 x86_64 unless the puppeteer version is mismatched.

Common situations: Running on FreeBSD or another uncommon Unix; a very old or very new puppeteer/browsers package whose platform list does not include the current combo; a misreported process.arch.

Related errors

• Chrome Headless Shell is not available for Linux ARM64 (DGX
• Cached Chrome binary was missing at ${fromCache.staleHyperfr
• [BrowserManager] Chrome binary not found at PRODUCER_HEADLES
• [BrowserManager] Chrome binary not found at HYPERFRAMES_BROW
• This composition declares data-requires-webgpu, but browser

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