> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-codex-docs-human-first-refactor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> 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 theme={null}
    npx hyperframes doctor
    ```

    This checks the runtime, browser, FFmpeg, and other local requirements.
  </Step>

  <Step title="Check the project">
    ```bash theme={null}
    npx hyperframes lint
    npx hyperframes check
    ```
  </Step>

  <Step title="Inspect the visible result">
    Open Studio or capture important frames:

    ```bash theme={null}
    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>

## Studio problems

### Studio does not open

Run `npx hyperframes preview` from the project folder and keep that terminal running.

If it still fails:

1. read the terminal error;
2. run `npx hyperframes doctor`;
3. try another port with `npx hyperframes preview --port 4567`;
4. restart the preview process.

### The preview is not updating

Confirm that you are editing a file inside the open project. Save the file, wait for refresh, and inspect the preview terminal for errors.

If needed, reload Studio or restart `npx hyperframes preview`.

### I cannot select or edit an element

Pause on a frame where the element is visible, then select it from Layers.

The element may belong to a group or nested composition, sit outside the frame, or use source that Studio cannot edit safely. Open the nested composition, use the inspector, or copy context to your agent.

### A move became animation

Auto-keyframing was probably enabled. Undo the edit, turn off the auto-keyframe control, and apply the layout change again.

### A timeline edit landed at the wrong time

Undo, zoom in, and place the playhead more precisely. Check whether snapping moved the boundary to a nearby clip or beat.

Continue to [Studio troubleshooting](/studio/troubleshooting) for selection, editing, timeline, and save recovery.

## 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 theme={null}
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 theme={null}
  brew install ffmpeg
  ```

  ```bash Ubuntu or Debian theme={null}
  sudo apt install ffmpeg
  ```

  ```powershell Windows theme={null}
  winget install ffmpeg
  ```
</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.

## 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 theme={null}
<div id="video-wrapper">
  <video src="./assets/video.mp4" style="width:100%;height:100%"></video>
</div>
```

```javascript theme={null}
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 theme={null}
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 theme={null}
<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 theme={null}
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 theme={null}
npx hyperframes render --docker --output output.mp4
```

### The render is slow

During iteration:

* use draft quality;
* render a shorter range or inspect snapshots;
* resize large source media;
* simplify expensive filters;
* avoid increasing resolution or frame rate before needed.

Run `npx hyperframes benchmark` when tuning worker settings.

### 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 theme={null}
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.