Troubleshooting

HeadlessExperimental.beginFrame' wasn't found (first thing to check)

Symptom: npx hyperframes render fails with:

✗ Render failed
Protocol error (HeadlessExperimental.beginFrame):
'HeadlessExperimental.beginFrame' wasn't found

Cause: Chromium 147+ removed the HeadlessExperimental.beginFrame CDP command. This affected sandbox environments (e.g., OpenClaw, some containerized agent hosts) that ship modern Chromium as the system browser. See hyperframes#294.

Fix (permanent — preferred): upgrade.

npx hyperframes upgrade -y
# or
npm install -g hyperframes@latest

hyperframes >= 0.4.2 auto-detects whether the resolved browser supports beginFrame (checks for chrome-headless-shell in the binary path) and falls back to screenshot capture mode when it doesn't. Commit 4c72ba4 (March 2026) shipped this auto-detect.

Fix (escape hatch — if you can't upgrade):

export PRODUCER_FORCE_SCREENSHOT=true
npx hyperframes render

This forces screenshot mode regardless of the binary. Screenshot mode is slightly slower but visually identical.

Fix (prevent — recommended): install chrome-headless-shell so the engine can use the fast BeginFrame path:

npx puppeteer browsers install chrome-headless-shell
# or let the CLI do it
npx hyperframes browser --install

scripts/setup.sh runs this automatically.

npx hyperframes render hangs for 120s then times out

Cause: the resolved browser is system Chrome (e.g., /usr/bin/google-chrome) and doesn't support the BeginFrame path, but auto-detect also missed it (older hyperframes version).

Fix:

1. Check which binary is being used: npx hyperframes browser --path
2. If it's system Chrome, either:
   • Install chrome-headless-shell: npx hyperframes browser --install, OR
   • Set the escape hatch: export PRODUCER_FORCE_SCREENSHOT=true, OR
   • Upgrade: npx hyperframes upgrade -y

ffmpeg: command not found

Install FFmpeg via your system package manager:

Verify: ffmpeg -version.

Node version X is not supported

HyperFrames requires Node.js >= 22. Check with node --version.

• nvm: nvm install 22 && nvm use 22
• Homebrew (macOS): brew install node@22 && brew link --overwrite node@22
• apt: follow nodesource for Node 22 LTS.

ENOSPC: no space left on device or OOM kills during render

Renders are memory- and disk-hungry. Minimums:

• RAM: 4 GB free (8 GB recommended for 60fps / --quality high)
• Disk: 2 GB free scratch space — frames are written to /tmp during capture

Mitigations:

• Lower quality: --quality draft.
• Lower fps: --fps 24.
• Lower worker count: --workers 1.
• Set TMPDIR to a volume with more space: export TMPDIR=/mnt/scratch.

Lint passes but the render is blank / black frames

Check the browser console in preview — usually:

• A timeline was registered with the wrong key (__timelines["typo"] instead of __timelines["root"]).
• The root composition was wrapped in <template> (only sub-compositions use <template>).
• A script tag failed to load — check Network tab in preview.

Run npx hyperframes lint --verbose to see info-level findings.

Contrast warnings from hyperframes validate

⚠ WCAG AA contrast warnings (3):
  · .subtitle "secondary text" — 2.67:1 (need 4.5:1, t=5.3s)

• Dark backgrounds: brighten the failing color until it clears 4.5:1 (normal text) or 3:1 (large text — 24px+ or 19px+ bold).
• Light backgrounds: darken it.
• Stay within the palette family — don't invent a new color, adjust the existing one.
• Skip the check temporarily with --no-contrast if iterating rapidly, but clear it before delivery.

Font family 'X' not supported by compiler

The compiler embeds a curated set of web-safe + open-source fonts. If a font isn't supported, either:

• Swap to a supported alternative from the warning.
• Register a custom font via @font-face pointing to a .woff2 in the project directory (the compiler embeds referenced @font-face files).

Video plays back muted or with no audio

Check:

• The <video> element has muted playsinline (required — browser autoplay policy).
• Audio is a separate <audio> element, not the video element.
• Audio data-volume is set (defaults to 1).
• The audio file is at the expected path — compositions load relative to their own directory.

Docker render fails on Linux with rootless Docker

Add --privileged or pass --cap-add=SYS_ADMIN:

npx hyperframes render --docker --docker-args "--cap-add=SYS_ADMIN"

The headless browser needs namespace permissions for sandboxing.

Runaway CPU from leftover preview workers

Symptom: load average climbs and stays high; top shows several chrome-headless-shell --type=gpu-process at ~300%+ CPU each, alive for hours/days, even when you're not rendering.

Cause: npx hyperframes preview is a long-lived server that keeps Chrome render workers resident. On hosts with no real GPU (WSL, containers, most CI), each idle worker falls back to software WebGL (swiftshader) whose GPU process busy-spins a CPU core. A preview left open — or several started over time — stacks these up.

Diagnose:

pgrep -af chrome-headless-shell        # list the workers + their parent flags
pgrep -af "hyperframes.*preview"       # the preview server(s) holding them open
uptime                                 # confirm elevated load average

Fix: stop the preview server and its workers (see SKILL.md#cleanup):

pkill -f "hyperframes.*preview"
pkill -f chrome-headless-shell         # only if no other tool uses it — check pgrep first

Avoid: never leave a preview running after review; use render (one-shot, self-cleaning) for output. Keep --workers low on shared/GPU-less hosts.

Bug reports

Include npx hyperframes info output + the full error log. File at github.com/heygen-com/hyperframes.