hermes-agent/optional-skills/creative/hyperframes/references/troubleshooting.md

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:

OS / distro	Command
Ubuntu / Debian	sudo apt-get install -y ffmpeg
Fedora / RHEL	sudo dnf install -y ffmpeg
Arch	sudo pacman -S ffmpeg
macOS	brew install ffmpeg
Windows	winget install Gyan.FFmpeg

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.

Bug reports

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