> ## 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.

# Get unstuck

> Start with what you can see, try the smallest useful fix, and get back to your HyperFrames task.

Find the symptom that looks like yours below — the contents list on the right jumps straight to it. You should not need to understand the rendering architecture to solve a normal problem.

## Studio will not open

The browser never opens, the page is unreachable, or the project does not load.

1. Open a terminal in the HyperFrames project folder.
2. Run `npx hyperframes preview`.
3. Keep that process running while Studio is open.
4. Use the local URL printed in the terminal.

If the command cannot find a project, check that you are inside the project folder rather than its parent.

## Preview is wrong or stale

A saved change is missing, playback looks old, or the preview is blank. Try these in order:

1. Save the changed file.
2. Reload Studio once.
3. Check the terminal for a build or runtime error.
4. Run the project checks:

```bash theme={null}
npx hyperframes lint
npx hyperframes check
```

`lint` checks the composition structure. `check` opens the project in a browser gate and catches runtime, layout, motion, and contrast problems.

## I cannot select or edit something

Selection, canvas controls, timing, or an Inspector field is unavailable.

* Open **Layers** and select the element there when clicking the canvas is difficult.
* Confirm you are in **Preview**, not Storyboard.
* Scrub to a time where the element is actually visible.
* Check whether the visual lives inside a nested composition.
* Ask the agent when the change affects source structure rather than one visible element.

[Open Studio troubleshooting →](/studio/troubleshooting)

## Media is missing or black

An image, video, font, or audio file is absent or does not render. Check that:

* the file still exists inside the project;
* the path and filename capitalisation match;
* the source is local and available during rendering;
* the browser can decode the format;
* the media is visible at the current time;
* the terminal reports no download, decode, or CORS error.

Never rely on a temporary signed URL or a render-time network request. Ask the agent to copy required media into the project.

## Animation is wrong

Motion jumps, drifts, starts at the wrong time, or changes after seeking. First decide whether it happens:

* during normal playback;
* only after scrubbing;
* only in the final render.

That distinction separates a timeline mistake from non-deterministic animation. HyperFrames animation must be seekable: the same frame should look the same every time it is requested.

Run `npx hyperframes check`, then give your agent the smallest affected scene and the exact timestamp.

## Render failed or differs from preview

Export stops, produces the wrong result, or disagrees with Studio.

1. Preserve the complete render error.
2. Run `npx hyperframes check`.
3. Confirm fonts and media are local and load before capture.
4. Check the affected timestamp in Studio.
5. Try the normal MP4 preset before changing codecs or advanced flags.

The [complete troubleshooting guide](/guides/troubleshooting) covers codec, browser, FFmpeg, GPU, HDR, and deployment-specific failures.

## Copy a useful diagnostic

If none of the above resolved it, send this to your agent with the visible facts filled in:

```text theme={null}
What I was trying to do:

What I clicked or ran:

What I expected:

What happened instead:

Exact error:

Where it happens: Studio / lint / check / render

Does it happen every time?

HyperFrames version:

Operating system:

Affected file or timestamp:
```

Add a screenshot or short recording when the failure is visual. Never paste access tokens, credentials, or private media into a public issue.

## Still stuck

<CardGroup cols={2}>
  <Card title="Common questions" icon="circle-question" href="/guides/common-questions">
    Short answers to what usually comes up during first use.
  </Card>

  <Card title="Complete troubleshooting" icon="wrench" href="/guides/troubleshooting">
    Less common project, media, animation, rendering, and environment failures.
  </Card>

  <Card title="Share product feedback" icon="comment" href="/guides/feedback">
    Explain a confusing or broken experience with useful context.
  </Card>

  <Card title="Search GitHub issues" icon="github" href="https://github.com/heygen-com/hyperframes/issues">
    Find a known problem, or open a reproducible one.
  </Card>
</CardGroup>