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

# Troubleshooting

> What each DeckTalk warning, verdict, and failure means, from phrase not found and missing keys to NO COVER, BLACK?, TRUNCATED, KATEX?, OFF CUE, and NO CHANGE, and what to do about it.

Run `decktalk build --silent` first when something goes wrong. It removes the voice from
the picture, costs nothing, and shows whether the problem is in the cues, the pages, or
the assembly.

<AccordionGroup>
  <Accordion title="phrase not found">
    The `beats` stage could not find a cue's `on` phrase among the spoken words of its
    section, and `build` stopped.

    ```text theme={null}
     03    37.1      -  3.1@0.0,3.1draw@1.85,3.1a@9.74,3.1think@25.97,3.1c@31.27
                        ! 3.1b: phrase not found: 'expand the 2'
    ```

    Compare the phrase with the words in `build/audio/NN-slug.words.json`. The usual
    causes are a number written as digits, a symbol, a hyphen that joins two words into
    one token, or a phrase that spans a stage direction. Write the phrase as the voice
    says it. The `--allow-unresolved` flag builds without the cue.
  </Accordion>

  <Accordion title="ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID not set">
    Copy `.env.example` to `.env` beside `decktalk.toml` and replace both placeholders.
    A value still wrapped in angle brackets counts as unset. Exported variables work
    too. A silent build needs neither.
  </Accordion>

  <Accordion title="ProviderError: 401 or 402 from ElevenLabs">
    A 401 means the key is wrong or was revoked. A 402 or a quota message means the plan
    has no characters left. Some voices need a paid plan. `decktalk narrate --dry-run`
    shows the exact text a build would send, and the [FAQ](/help/faq#what-does-it-cost)
    has the plan arithmetic.
  </Accordion>

  <Accordion title="NO COVER in measure or check">
    The recording has no magenta run at its start, so `measure` guessed the trim from the
    first painted frame. The page probably removed the cover itself, or a page written by
    hand started its clock at load instead of waiting for `DeckTalk.startClock()`. Make
    sure the page includes the packaged runtime, and run `decktalk runtime` after an
    upgrade. Raise `min_lead_seconds` under `[record]` if the machine is very slow.
  </Accordion>

  <Accordion title="BLACK? or TRUNCATED in check">
    A black recording usually means the page threw before it rendered, and the recorder
    logs page errors as warnings. Open the page with `?scene=N&hud=1` in a browser. A
    truncated recording is shorter than the section needs, which happens when Chromium
    was killed or the machine stalled. Re-record that section with `--only N`.
  </Accordion>

  <Accordion title="KATEX? in check, or equations that stay plain text">
    The page reported that KaTeX never loaded, so every `data-tex` element kept its
    fallback text. A project created before `decktalk setup` cached KaTeX loads it from
    a CDN, which fails offline. Run `setup`, then either run `init` again or copy the
    cached `katex` directory into `deck/` and point the two tags at `./katex/`.
    [Build in CI and offline](/guides/ci-and-offline#offline) has the tags. `decktalk doctor`
    shows whether the cache is present.
  </Accordion>

  <Accordion title="BLACK section start in verify">
    The final mp4 opens a section on a dark frame. Check that the first cued step of the
    scene renders something at t=0, and that `extra_seconds` is not zero. Raise
    `after_dip_seconds` under `[verify]` if the dip to black is deliberately long.
  </Accordion>

  <Accordion title="NO CHANGE for a cue in verify">
    The picture did not change enough across the cue, or changed no more than it was
    already changing. A very small or very slow reveal can fail this check while looking
    right. Take a frame with `decktalk shots --section N --at S` just after the cue to
    see what happened. If the reveal is deliberately subtle, lower `min_changed_percent`
    under `[verify]`, or lengthen `probe_delays` for a slow animation.
  </Accordion>

  <Accordion title="OFF CUE for a cue in verify">
    The picture changed, but the first changed frame sits further from the cue than
    `max_offset_frames` allows, and the note says by how much. A negative offset means
    something moved before the cue, usually an earlier reveal still settling or an
    element with `data-at` that fires on the mount. A positive offset larger than a frame
    or two usually means the effect has a delay of its own, such as a CSS transition on
    the element. Use `decktalk shots --section N --at S` around the cue to see the frames,
    and raise `max_offset_frames` only when the delay is intended.
  </Accordion>

  <Accordion title="A typewriter reveal fails the cue check">
    An element with `data-type` types one character every few tens of milliseconds, so
    the first probe after the cue sees only a few characters and a short line may fall
    under `min_changed_percent`. Give the element's container something that appears at
    once on the same cue, as the scaffold's chat bubble does with `data-fx="fade"` on the
    bubble and `data-type` on its text. Then the background lands on the cue and the
    text follows.
  </Accordion>

  <Accordion title="A section is early or late by a fixed amount">
    Open the section's sidecar `build/rec/NN-scene.json` and look at `lead_method`.
    Anything but `cover (…)` means the alignment was guessed. Re-record with
    `decktalk record --only N` followed by `decktalk measure --only N`, then assemble.
  </Accordion>

  <Accordion title="unknown cue id in the recorder's log">
    The page recorded a cue in `?beats=` that no step owns. `beats` resolves phrases
    without checking ids against the page, so a typo in `cues.json` shows up here. The
    warning is also written to the sidecar. Check the id against the step ids and their
    `cues` lists, and remember that a cue belongs to the step whose id is its longest
    prefix. [The page contract](/concepts/page-contract#cue-ownership) has the rules.
  </Accordion>

  <Accordion title="The clip plays as a titled slate">
    The file named by `clip` does not exist, so a slate plays for `slate_seconds`. Drop
    the file in place, or delete the section from both `decktalk.toml` and `script.md`.
    The `--strict` flag makes this an error instead.
  </Accordion>

  <Accordion title="hold_seconds is allowed only on the last page section">
    The narration is one continuous track, so a hold on an earlier section would push
    every later visual off its words. Move the hold to the last page section, or split
    the video.
  </Accordion>

  <Accordion title="The index page is empty, or window.__decktalk is missing">
    The page does not include `decktalk-runtime.js`, or the script tag comes after the
    scene definitions. Include the runtime first, then define scenes.
  </Accordion>

  <Accordion title="Loudness warnings on a silent build">
    A silent build's mix is silence, so the loudness pass has nothing to measure and
    reports a miss. The warning is expected and harmless. Do not combine `--silent`
    with `--strict`, which turns the miss into an error.
  </Accordion>

  <Accordion title="Windows">
    DeckTalk runs its own test suite and a full offline build on Windows in CI. Paths in
    `decktalk.toml` use forward slashes on every platform. The `setup` command puts
    Chromium under `%LOCALAPPDATA%\ms-playwright`. If a corporate proxy blocks that
    download, set `PLAYWRIGHT_DOWNLOAD_HOST` as Playwright documents.
  </Accordion>

  <Accordion title="Slow builds">
    Encoding dominates. Set `DECKTALK_VIDEO_PRESET=veryfast` for drafts, or put
    `preset = "veryfast"` under `[video]` in the project. The final render can go back to
    `medium`. A full silent build of the scaffold takes under two minutes on a laptop.
  </Accordion>
</AccordionGroup>

If none of this fits, open an issue with the output of `decktalk doctor` and the
`[[section]]` tables involved. The bug report template asks for exactly that.