Html2MP4Powered by HyperFrames
Tutorial How it works

Home / Render troubleshooting

HyperFrames render slow or stuck: causes and fixes

If npx hyperframes render is crawling or sits at the same percentage for minutes, the cause is usually one of a handful of known issues: an old version, low memory, a heavy page load, WSL2 graphics or temp-disk space. Here is how to tell which one you have and the official flags that fix it.

Four steps to fix a slow or stuck HyperFrames render: doctor, update, draft or low-memory mode, timeouts and cache directory
Work down the list before you open an issue

Last checked against HyperFrames 0.8.183 and the official docs on October 21, 2026. Html2MP4 is an independent guide, not affiliated with HeyGen.

How long should a HyperFrames render take?

HyperFrames renders by opening your composition in headless Chrome, seeking to every frame, taking a screenshot and encoding the frames with FFmpeg. That makes output deterministic, but every frame is a real browser paint, so render time grows with length, resolution, frame rate, effects and the hardware you run on. Some public data points:

  • A 36-second render took about 4 minutes on a 2-core Linux box (post on X).
  • A 7:23 composition under WSL2 took 48 minutes on software rendering. The same machine rendering natively on Windows was about 5x faster (issue #5548).
  • A creator reported an 8-hour single-pass render for a 4-minute explainer (post on X).

So a slow render is not always a bug. A render that shows no progress for many minutes usually is, and those cases are covered below.

First steps for any slow or stuck render

npx hyperframes doctor          # runtime, browser, FFmpeg
npx hyperframes lint            # composition mistakes
npx hyperframes check           # lint + runtime + layout checks
npx hyperframes@latest render -o out.mp4   # many render hangs were fixed in later versions

Most of the hangs listed below were fixed upstream, so updating is the cheapest fix. If you pin a version in package.json, the docs suggest npx hyperframes@latest upgrade --project . --check to preview the change first.

HyperFrames render stuck: symptoms and fixes

Stuck on “Initializing calibration session…”

This was a regression in v0.6.74 on an Apple M4. It produced a 33-comment thread, the longest in the repo, and was fixed by v0.6.80 (issue #1231). Update HyperFrames. If you are still stuck on a current version, try one worker (-w 1) or --low-memory-mode. Both skip the auto-worker calibration.

Stuck at 5% or 25% with no log output (low-memory machines)

On an 8 GB machine, renders sat at 5% or 25% for 5–15 minutes with no feedback, then finished or timed out (issue #1218). The current CLI auto-detects machines with 8 GB of RAM or less. You can also force the safe profile and give Chrome more time:

npx hyperframes render --low-memory-mode -o out.mp4
npx hyperframes render --protocol-timeout 600000 --player-ready-timeout 90000 -o out.mp4

“Navigation timeout of 60000 ms exceeded”

Heavy compositions with many videos, fonts or asset files can miss the 60-second page-load budget (issue #1199). Raise it (the value is in seconds), and prefer local assets over remote URLs:

npx hyperframes render --browser-timeout 180 -o out.mp4

Every render takes about 45 seconds longer than it should

According to the official docs, a composition that never registers a GSAP timeline makes the renderer wait for the 45-second player-ready timeout on every render. Either register your timeline on window.__timelines, or mark the root with data-no-timeline. npx hyperframes lint reports this as missing_data_no_timeline.

Slow under WSL2 (“browserGpuMode probe → software”)

Headless Chrome in WSL2 may not reach the GPU and falls back to software rendering (issue #5548). The official fix is to add yourself to the render group and restart WSL. If that does not help, render from a normal Windows folder in PowerShell:

sudo usermod -aG render $USER
# then in Windows PowerShell:
wsl --shutdown

Windows: the render is refused for disk space, or the temp drive fills up

Renders write temporary frames, and one report shows a disk-headroom check refusing a 1-minute 1080p export on a machine with 18 GB free (issue #4060). Move the frame cache to a bigger drive:

npx hyperframes render --frames-cache-dir D:\hf-cache -o out.mp4

Docker render times out

--docker pins the render environment, but it adds its own failure points. Docker renders timed out at 25% on macOS (issue #1195). Run docker info first. If you do not need a pinned environment, try a local render.

How to make HyperFrames render faster

  • Iterate on draft quality: npx hyperframes render -q draft. Switch to -q delivery only for the final export.
  • Check single frames before a full render: npx hyperframes snapshot --at 0,3,8.
  • Tune workers: each worker is a separate Chrome process (about 256 MB RAM). Run npx hyperframes benchmark before setting -w by hand.
  • Trim expensive effects: large backdrop-filter blurs, heavy shadows and oversized images cost time on every frame.
  • Do not raise resolution or fps until the cut is final.

Still stuck?

Run npx hyperframes info, then search the HyperFrames GitHub issues or open a new one. Include the exact error, your HyperFrames version and OS, and whether the problem happens in preview, checks or render. Many of the bugs listed above have already been fixed upstream.

Rather not render on your own machine?

Local rendering is free but uses your CPU, RAM and disk. HeyGen offers cloud rendering through its hosted HyperFrames MCP connector (beta). Html2MP4 is building a browser editor where you pick a template, change the text and brand, preview it, and download the MP4 rendered on our servers. You will not need Node, FFmpeg or a local Chrome. It is in early access: see how it will work.

Setting up from scratch? Start with how to install HyperFrames and the HyperFrames tutorial.