Chrome Headless Shell is not available for Linux ARM64 (DGX

Error message

Chrome Headless Shell is not available for Linux ARM64 (DGX Spark, GB10, Jetson).\n\nInstall Chromium manually and point hyperframes to it:\n\n  sudo apt-get install -y chromium-browser\n  export HYPERFRAMES_BROWSER_PATH=$(which chromium-browser)\n\nThen re-run your command. The HYPERFRAMES_BROWSER_PATH env var persists for the session.

What it means

Thrown by ensureLinuxArmBrowser() on Linux ARM64 (isLinuxArm() true) when no browser is found via env/cache/system AND apt-based auto-install of chromium-browser either failed or did not produce a usable binary. chrome-headless-shell has no Linux ARM64 build, so on DGX Spark / GB10 / Jetson the tool falls back to system Chromium; when that also can't be obtained automatically, it errors with manual install instructions.

Source

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

      timeout: 120_000,
    });

    if (result.status === 0) {
      const afterInstall = await findBrowser();
      if (afterInstall) {
        console.error(`\n✅ Chromium installed at ${afterInstall.executablePath}\n`);
        return afterInstall;
      }
    } else {
      // apt succeeded but binary not found, or apt failed — fall through to helpful error.
      console.error("\n⚠️  apt-get exited with errors. Trying anyway...\n");
      const afterAttempt = await findBrowser();
      if (afterAttempt) return afterAttempt;
    }
  }

  // Could not auto-install — give clear manual instructions.
  throw new Error(
    `Chrome Headless Shell is not available for Linux ARM64 (DGX Spark, GB10, Jetson).\n\n` +
      `Install Chromium manually and point hyperframes to it:\n\n` +
      `  sudo apt-get install -y chromium-browser\n` +
      `  export HYPERFRAMES_BROWSER_PATH=$(which chromium-browser)\n\n` +
      `Then re-run your command. The HYPERFRAMES_BROWSER_PATH env var persists for the session.`,
  );
}

/**
 * Find or download a browser.
 * Resolution: env var -> cached download -> system Chrome -> auto-download.
 * With `preferManagedChrome`: env var -> OUR pinned cache -> auto-download
 * (puppeteer-cache preference and system Chrome are both skipped).
 */
export async function ensureBrowser(options?: EnsureBrowserOptions): Promise<BrowserResult> {
  const fromEnv = findFromEnv();
  if (fromEnv) return fromEnv;

View on GitHub (pinned to c2996c8626)

Solutions

Install Chromium manually and point hyperframes at it: `sudo apt-get install -y chromium-browser` (or your distro's package), then `export HYPERFRAMES_BROWSER_PATH=$(which chromium-browser)`.
If the package name differs (Debian uses 'chromium'), install that and set HYPERFRAMES_BROWSER_PATH to its path.
On non-Debian ARM distros, use the distro's package manager (dnf/pacman) to install chromium, then set the env var.
Re-run your command after exporting HYPERFRAMES_BROWSER_PATH (persists for the session).

Example fix

# before — ARM64, no browser, auto-install failed
$ hyperframes render ...
# install + point at it
$ sudo apt-get install -y chromium-browser
$ export HYPERFRAMES_BROWSER_PATH=$(which chromium-browser)
$ hyperframes render ...

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from 'node:fs';
function armBrowserConfigured(): boolean {
  return Boolean(process.env.HYPERFRAMES_BROWSER_PATH) && existsSync(process.env.HYPERFRAMES_BROWSER_PATH);
}
if (process.arch === 'arm64' && process.platform === 'linux' && !armBrowserConfigured()) {
  throw new Error('Set HYPERFRAMES_BROWSER_PATH to a Chromium binary on Linux ARM64.');
}

Type guard

function isLinuxArm(): boolean {
  return process.platform === 'linux' && process.arch === 'arm64';
}

Try / catch

try {
  await ensureBrowser();
} catch (err) {
  if (/Chrome Headless Shell is not available for Linux ARM64/i.test((err as Error).message)) {
    console.error('Install chromium-browser and: export HYPERFRAMES_BROWSER_PATH=$(which chromium-browser)');
  }
  throw err;
}

Prevention

On Linux ARM64, pre-install Chromium and set HYPERFRAMES_BROWSER_PATH in your shell profile.
Bake Chromium into ARM Docker images so the manual step is unnecessary.
For non-Debian ARM distros, use the distro's chromium package name.

When it happens

Trigger: Running on aarch64 Linux; HYPERFRAMES_BROWSER_PATH unset; no cached or system Chrome; either apt-get is unavailable (non-Debian ARM like Fedora/RHEL/Arch ARM) or apt-get install chromium-browser failed (package not found, no sudo, offline).

Common situations: Jetson/NVIDIA ARM device with a non-Ubuntu distro; a restricted environment without sudo; apt package is named differently (e.g. 'chromium' not 'chromium-browser' on some Debian versions); offline ARM box.

Related errors

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