> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clayzo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> The problems people hit, and what they mean.

<AccordionGroup>
  <Accordion title="Text is missing but everything else renders">
    No font was found for that text run. Nothing substitutes and nothing warns in the frame. Embed the font as a `font` asset with a `uri` next to the document, and reference it with `fontAssetId`. In the browser, supply a `familyFontLoader` for family-name runs, or package the document as `.clayzo`. The CanvasKit player's `onPrewarm` reports `unresolvedFamilies`. See [Fonts and assets](/authoring/fonts-and-assets).
  </Accordion>

  <Accordion title="The export has a black (or transparent) background">
    Frames are transparent wherever nothing is drawn, and `canvas.backgroundColor` is metadata. Draw a full-canvas `rect` as the first root node.
  </Accordion>

  <Accordion title="Export is slow">
    Cost is per layer, not per second: opacity below 1, isolated groups, shadows and every effect add an offscreen pass per frame, and glass, refraction and custom shaders are evaluated per pixel. Exports render on the GPU only when Chrome, Edge, Brave or Chromium is installed; without one, install one or export from `clayzo preview`. In the document, animate `style.fill.opacity` instead of node `opacity` on solid shapes.
  </Accordion>

  <Accordion title="Something doesn't draw in the WebGL player but does in the preview">
    The document uses a construct the WebGL player doesn't cover: a matte, a nested clip, or a shader calling a colour-space intrinsic. Run `checkCoverage` and read `reasons`. Change the document, or ship the CanvasKit player for it. See [Choosing a renderer](/playback/choosing-a-renderer).
  </Accordion>

  <Accordion title="An export says its ffmpeg can't export sound">
    Run `npx clayzo update`, or export the picture alone with `--no-audio`.
  </Accordion>

  <Accordion title="An interactive piece looks wrong in the video">
    Exports don't run bindings; every bound property exports at its keyframed value. Author the resting pose into the timeline and let bindings `add` to it. See [Interactivity](/authoring/interactivity).
  </Accordion>

  <Accordion title="CLAYZO_AUTH_REQUIRED">
    The command needs a sign in. Run `npx clayzo login`, or set `CLAYZO_TOKEN` in CI. See [Authentication](/authentication).
  </Accordion>

  <Accordion title="CLAYZO_VERSION_UNSUPPORTED">
    The installed CLI is older than the minimum the service supports. Run the command in the error, usually `npx clayzo update`, which updates the CLI, the project's packages and the skills together.
  </Accordion>

  <Accordion title="CLAYZO_UPDATE_FAILED">
    A package manager command that `clayzo update` ran failed. The error names the command; run it yourself to see the full output. For a machine-wide npm install that fails with `EACCES`, npm can't write to its global folder: see npm's guide to [resolving EACCES permissions errors](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally).
  </Accordion>

  <Accordion title="CLAYZO_INIT_CLI_OLDER">
    The project already has newer Clayzo packages than the `clayzo` running `init`, which would downgrade them. Run `npx clayzo update` first, or run `npx clayzo@latest init`.
  </Accordion>

  <Accordion title="CLAYZO_LOGIN_EXPIRED">
    The device code wasn't approved in time. Run `npx clayzo login` again and approve it in the browser.
  </Accordion>

  <Accordion title="The preview port is still in use">
    A previous preview is still running. It prints its process id on startup; stop it with `kill <pid>`. Previews also stop themselves after ten minutes with no browser attached.
  </Accordion>

  <Accordion title="The React player rebuilds on every render">
    `options` or a callback changes identity each render, which recreates the player. Build `options` with `useMemo` and keep callbacks stable. See [React and Next.js](/playback/react).
  </Accordion>

  <Accordion title="A keyframe never seems to land on a frame">
    Ticks are the time base, and frames are a multiple of them. At 240 ticks per second and 30 fps a frame is 8 ticks; at 60 fps it's 4. Snap keyframes to that grid.
  </Accordion>
</AccordionGroup>

Still stuck? Email [team@clayzo.com](mailto:team@clayzo.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.