Docker render: Navigation timeout at 25% during frame capture (macOS 26.5.1 M4)

[sarichan777]

Describe the bug

npx hyperframes render --docker consistently times out at 25% with Navigation timeout of 60000 ms exceeded. Local rendering is also broken on macOS 26.5.1 due to an OS-level ReadPixels GPU stall. Docker mode is the only path forward on this OS version.

Link to reproduction

N/A - Docker rendering issue reproducible with any self-contained composition

Steps to reproduce

1. Create a self-contained HyperFrames composition with all assets in a single directory
2. Run: cd /path/to/composition && npx hyperframes render --docker --composition .
3. Watch progress stall at 25% then timeout after 60s

Expected behavior

HyperFrames should render the composition to MP4 inside Docker without timing out. Frame capture should start and complete at normal speed.

Actual behavior

Navigation timeout after 60s at 25%. Chrome-headless-shell inside Docker never fires the page load event. Log: render failed with Navigation timeout of 60000 ms exceeded

Environment

macOS 26.5.1 (25F80) Apple M4 (ARM64)
HyperFrames 0.6.69 (0.6.56, 0.6.70 also tested)
Docker 29.4.3
Node.js v24.16.0
FFmpeg 8.0

Additional context

Attempted fixes: --workers 1, --workers auto; PRODUCER_FORCE_SCREENSHOT=1; self-contained render directories with 100% asset coverage; multiple HyperFrames versions (0.6.56, 0.6.69, 0.6.70). All fail the same way.

[sarichan777]

Thank you for the incredibly fast turnaround. Confirming the root cause makes sense - I was seeing exactly the emulation SEGV you described on M4. Looking forward to testing once the PR lands. Much appreciated.

[jrusso1020]

We dug into this and the bug-fix PR is now up: #1196.

What we could / couldn't reproduce on a near-identical environment (macOS 26.5 / Apple M4 Max, ARM64, Node 22.20.0, FFmpeg 7.1.1, Docker 28.0 via colima, HyperFrames 0.6.71):

• ❌ Local render GPU stall — we did not reproduce this. npx hyperframes render (no --docker) completed cleanly: 300/300 frames captured, 18.2 KB MP4 produced in ~11s. No ReadPixels error, no GPU stall. So the "OS-level macOS 26.5.1 ReadPixels bug" claim is unverified from our side — it may be a more environment-specific issue than the report suggests.
• ✅ --docker render failure on Apple Silicon — reproduced cold. The failure manifestation we hit was a chrome-headless-shell SIGSEGV under qemu (qemu: unknown option 'type=gpu-process') rather than the reported 60s navigation timeout, but the root cause is the same.

Root cause

packages/cli/src/utils/dockerRunArgs.ts and packages/cli/src/commands/render.ts both hardcoded --platform linux/amd64 for the docker build and run commands. On an arm64 host that forces qemu emulation of x86_64 chrome-headless-shell, which is unreliable — depending on exact qemu/colima versions it either segfaults (us) or hangs on page navigation (this report).

The Dockerfile itself (Dockerfile.render) was already platform-agnostic. The pin lived purely in the CLI, with the comment "chrome-headless-shell doesn't ship ARM Linux binaries" — true (Chrome for Testing only ships linux64), but the cure was worse than the disease.

Fix in #1196

• Derive --platform from process.arch so arm64 hosts get a native linux/arm64 build with no qemu.
• Skip the chrome-headless-shell install on arm64 in the Dockerfile (no linux-arm64 binary exists) and let the engine fall back to the system chromium already installed via apt and pointed at by PUPPETEER_EXECUTABLE_PATH.
• Trade-off: arm64 renders use screenshot capture instead of HeadlessExperimental.beginFrame, so output isn't byte-identical to amd64 renders. We print a one-line warning. End-user output is correct; only golden-baseline pixel comparisons against amd64 are affected.

Verified end-to-end: the same blank scaffold that SEGV'd before the fix now completes in 1m18s wallclock (most of that is the one-time arm64 image build).

If you can run npx -y hyperframes@latest render --docker from your environment once #1196 lands, that would confirm the fix carries across the slightly different patch level (26.5 vs 26.5.1).

[sarichan777]

Will test on 26.5.1 as soon as the PR lands and confirm here. Thanks for the deep investigation and the quick fix.

[sarichan777]

You all are an incredible team — root cause to PR to thorough review in minutes. The attention to edge cases (Rosetta x64 Node, --gpus, HYPERFRAMES_DOCKER_PLATFORM env override) is exactly the kind of care that makes early adoption worthwhile. Still standing by to test on 26.5.1 once this lands.

[jrusso1020]

@sarichan777 checkout version 0.6.72 and see if it fixes your issue!

let us know if you still run into issues