hyperframes/docs/guides/troubleshooting.mdx

---
title: "Troubleshooting"
description: "Solve common Studio, project, media, animation, preview, and rendering problems."
---

Start with the symptom you can see. Keep the exact error and note whether the problem happens in Studio, validation, or only in the final render.

## Start here

<Steps>
  <Step title="Check the machine">
    ```bash
    npx hyperframes doctor
    ```

    This checks the runtime, browser, FFmpeg, and other local requirements.
  </Step>
  <Step title="Check the project">
    ```bash
    npx hyperframes lint
    npx hyperframes check
    ```
  </Step>
  <Step title="Inspect the visible result">
    Open Studio or capture important frames:

    ```bash
    npx hyperframes snapshot --at 0,3,8
    ```
  </Step>
  <Step title="Give the agent useful context">
    Copy the complete error and add what you did, what you expected, and what must not change.
  </Step>
</Steps>

For selection, canvas, timeline, autosave, and Studio-only failures, use
[Studio troubleshooting](/studio/troubleshooting).

## Project and environment problems

### "No composition found"

The project needs an `index.html` containing a valid composition root with `data-composition-id`, width, and height.

Create a new project:

```bash
npx hyperframes init my-video
```

Or compare the current source with [Compositions](/concepts/compositions).

### "FFmpeg not found"

FFmpeg is required for local video encoding.

<CodeGroup>
```bash macOS
brew install ffmpeg
```

```bash Ubuntu or Debian
sudo apt install ffmpeg
```

```powershell Windows
# Download a 64-bit Windows build from:
# https://ffmpeg.org/download.html#build-windows
# Then add its bin directory to PATH.
```
</CodeGroup>

Verify with `ffmpeg -version`, then rerun `npx hyperframes doctor`.

### Docker render will not start

Run `docker info`.

Confirm Docker is installed, its daemon is running, your user has permission, and the first image download can reach the registry.

### Preview checks an unexpected port range

When starting a managed background preview, choose the discovery range with an explicit port:

```bash
npx hyperframes preview --background --port 4567
```

Discovery checks ports 4567–4666. If this project has a saved preview on another
port outside that range, only that saved port is checked separately. When moving
an existing managed preview to the requested port, add `--force-new` to stop and
replace it. Without `--port`, discovery starts at the saved preview's port.

`preview --status --port 4567` uses the same discovery range and checks an
out-of-range saved port separately. Among previews for this project, status
prefers the exact requested port, then the saved preview's port, then another
match. The saved log path appears only when the selected server is verified as
that background preview. If the listener PID cannot be determined, JSON reports
`pid: null` and text output omits the PID.

`preview --stop` checks only this project's saved port when a session exists,
even with an explicit `--port`. Without a saved session, `--stop --port 4567`
discovers previews in ports 4567–4666. Shutdown waits check only the port being
stopped.

## Media problems

### Video is black in preview but renders

The browser may not decode the source codec even though FFmpeg can.

HyperFrames normally creates and uses a compatible preview proxy. If the frame remains black:

1. confirm automatic proxying is not disabled;
2. run `npx hyperframes doctor`;
3. run `npx hyperframes lint --verbose` to identify affected files;
4. confirm the source file exists and can be read.

### Video, image, or audio is missing

Prefer a local project asset. Confirm its path, filename capitalization, and whether it was moved or renamed.

Remote media can fail because of permissions, expiring URLs, or cross-origin restrictions.

### Preview stutters

Common causes:

- very large source images;
- several large `backdrop-filter` blurs;
- expensive shadows or filters on animated elements;
- too many large overlapping layers.

Check whether the slowdown occurs in one scene. Resize oversized media and simplify the expensive element before reducing the whole project’s quality.

## Animation and composition mistakes

These problems often appear in agent-written or manually edited source.

### A video freezes while its box animates

Do not animate `width`, `height`, `top`, or `left` directly on a `<video>` element.

Put the video inside a wrapper and animate the wrapper:

```html
<div id="video-wrapper">
  <video src="./assets/video.mp4" style="width:100%;height:100%"></video>
</div>
```

```javascript
tl.to("#video-wrapper", { width: 500, height: 280, x: 1200 }, 2);
```

### Media plays out of sync

Do not call `play()`, `pause()`, or set `currentTime` from composition scripts.

HyperFrames owns media playback. Use timing and media attributes to describe when the file should play.

### The composition ends too early

Check the resolved composition duration:

```bash
npx hyperframes compositions
```

A short animation timeline can make a project end before the underlying media. Extend the authored root duration or timeline using the correct pattern for that composition.

### A timed element is always visible

Timed visible elements need `class="clip"` as well as their timing attributes.

```html
<h1 class="clip" data-start="2" data-duration="5" data-track-index="0">
  Hello
</h1>
```

`npx hyperframes lint` normally catches this.

### Animation is static

Check that the animation is paused and registered using the exact composition ID.

```javascript
const timeline = gsap.timeline({ paused: true });
window.__timelines = window.__timelines || {};
window.__timelines["my-video"] = timeline;
```

`my-video` must match `data-composition-id="my-video"`.

### Changing root duration from a variable does nothing

The root render length is determined before composition scripts run. Author or generate the intended root `data-duration` directly.

Clip durations can still vary. See [Variables](/concepts/variables) for what may be changed safely.

## Render problems

### The render looks different from preview

Check fonts, remote media, browser-specific effects, and the actual exported file.

Use Docker when you need a pinned rendering environment:

```bash
npx hyperframes render --docker --output output.mp4
```

### Every render takes about 45 seconds longer than expected

A composition that never registers a GSAP timeline still makes the producer wait
for one. The producer polls `window.__timelines[<id>]` until the composition
player reports ready, then gives up after `player-ready-timeout` (45 s by
default). The wait is a fixed cost paid on every render, so it does not shrink
when you lower quality or resize media.

Declare that the composition has no timeline:

```html
<div
  data-composition-id="promo"
  data-no-timeline
  data-width="1920"
  data-height="1080"
  data-duration="6"
></div>
```

`npx hyperframes lint` reports the missing attribute as
`missing_data_no_timeline`. Compositions that do register a timeline are
unaffected: the poll returns as soon as the timeline appears, long before the
timeout.

To register a timeline instead of skipping the wait, see
[GSAP animation](/guides/gsap-animation).

### The render is slow

The causes below scale with the project. For a constant penalty on every render,
check the timeline poll above first.

During iteration:

- use draft quality;
- inspect snapshots before starting another full render;
- resize large source media;
- simplify expensive filters;
- avoid increasing resolution or frame rate before needed.

Run `npx hyperframes benchmark` when tuning worker settings.

### The render is slow under WSL2

WSL2 can expose a graphics card to Linux, but headless Chrome may not be able to use
it. The render then falls back to software rendering, which can be several times
slower on a long or effect-heavy video. The render log says so:

```text
[hyperframes] browserGpuMode probe → software (WebGL unavailable)
[hyperframes] WSL: the GPU check found no hardware GPU, so this render uses software WebGL ...
```

The lines after it say what HyperFrames checked. If they say your user is not in
the `render` group, add yourself, restart WSL, and render again:

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

If the GPU is still not used, render from Windows instead. Copy the project to
a Windows drive (for example `C:\Users\you\renders\my-video`) and run the same
command from PowerShell, where Chrome uses the graphics card through Direct3D:

```powershell
npx hyperframes render --output final.mp4
```

Run it from a normal Windows folder, not a `\\wsl.localhost\...` path.

### Expected HDR but received SDR

HDR needs a supported output and correct source color metadata. MP4 is the normal HDR output path; WebM and MOV may fall back to SDR.

Use `--hdr` only when the whole source and delivery workflow is intended for HDR. Read [HDR rendering](/guides/hdr) before delivery.

## Still stuck?

Run:

```bash
npx hyperframes info
```

Then search [GitHub issues](https://github.com/heygen-com/hyperframes/issues) or open a report with:

- the exact error;
- steps to reproduce;
- HyperFrames version and operating system;
- whether the issue occurs in preview, checks, or render;
- a small shareable project when possible.

Do not include secrets, private media, or access tokens.

## Related topics

- [Start with the shortest recovery path](/help)
- [Recover from a Studio-only problem](/studio/troubleshooting)
- [Share useful product feedback](/guides/feedback)