Troubleshooting

​

Find your message

​

setup, doctor, and keys

​

playwright install failed in setup

1. If the output names a network or proxy problem, set PLAYWRIGHT_DOWNLOAD_HOST as Playwright documents.
2. If you are on Linux, run decktalk setup as a user who can use sudo.
3. Run decktalk setup again.

​

KaTeX download failed in setup

1. When the machine is online, run decktalk setup again.
2. Run decktalk doctor and check that the katex row is ok.

​

MISSING or warning in doctor

• If chromium shows MISSING, Chromium does not launch.
• If ffmpeg shows MISSING, no ffmpeg exists in DECKTALK_FFMPEG, the static-ffmpeg download, or PATH.
• If katex shows warning, the KaTeX cache is empty. Pages load KaTeX from a CDN until you run setup.

1. Run decktalk setup.
2. Run decktalk doctor again.

​

KaTeX is not cached in init

1. Run decktalk setup.
2. Run decktalk init again into a new, empty directory.

​

is not empty in init

1. If you want a new project, pass an empty or new directory.
2. If you want to write into this directory, add --force. --force overwrites files that the scaffold also has.

​

must be letters in init

1. Pass a valid name with --name, such as --name my-lesson.

​

not set in narrate

1. If the project has no .env, run cp .env.example .env.
2. Replace both placeholder values in .env.
3. Run the command again.

​

HTTP 401 or HTTP 402 in narrate

• A 401 means that the key is wrong or was revoked.
• A 402 or a quota message means that the plan has no characters left, or that the voice needs a paid plan.

1. If the code is 401, copy a new key into .env.
2. If the code is 402, check the plan’s character balance with ElevenLabs.
3. Run decktalk narrate --dry-run to see the exact text that a build sends.

​

could not reach in narrate

1. Check the network connection and any proxy.
2. If you only need a rehearsal, run decktalk build --silent in a copy of the project.

​

Project files

​

decktalk.toml not found in any command

1. Run cd into the project directory.
2. If there is no project yet, run decktalk init DIR.

​

unknown table(s) in decktalk.toml

1. Compare the name with the known list in the error.
2. Rename or remove the table.

​

ignoring unknown key in decktalk.toml

decktalk.toml: [voice]: ignoring unknown key 'stabilty' (did you mean 'stability'?)

1. If the warning suggests a key, rename the key to that name.
2. If the warning says the key applies only to a page or clip section, move it to that kind of section.
3. Run the command again and check that the warning is gone.

​

must be in decktalk.toml

decktalk.toml: [soundscape.music]: 'seconds' must be int, got float

1. Look up the key’s type in decktalk.toml.
2. Change the value to that type.

​

invalid tuning value in decktalk.toml

1. Look up the field’s type in Configuration.
2. Correct the value where you set it.

​

narrate

​

unfilled placeholders in narrate

1. Run decktalk narrate --dry-run to list every placeholder.
2. Replace each placeholder in script.md.
3. If you want to voice the text as it is, pass --allow-placeholders.

​

no spoken sections match in narrate

error: no spoken sections match [5]; spoken sections are [1, 2, 3, 4, 6, 8, 9]

1. Pass a number from the list in the error.

​

have no [[section]] in decktalk.toml in narrate

1. If the section is new, add a [[section]] table with that number.
2. If the number is a typo, fix the heading in script.md.

​

have no narration yet in narrate

1. Run decktalk narrate with no --only.

​

holds voiced takes in narrate

error: build/audio/manifest.json holds voiced takes for sections 01. A silent run writes click tracks over those mp3 files and replaces the manifest, so the next voiced build voices every section again and spends credits on all of them. Rehearse the silent build in a copy of the project, or pass --force to replace the voiced takes.

1. If you want to rehearse, copy the project and run the silent build in the copy.
2. If you want to drop the voiced takes, run the same command with --force.

​

A section opens on its first word

1. Set lead_seconds on the page section in decktalk.toml. narrate joins that much silence in before the take and sends no request.
2. Run decktalk build --only N, so the recording covers the lead.

​

beats

​

phrase not found in beats

                    ! 3.4name: phrase not found: 'gradient decent'
 04    14.3      -  4.1out@2.65,4.1video@7.42,4.1parts@9.0,4.1script@11.12,4.1start@12.71
 06    20.9      -  6.1step@2.61,6.1four@5.22,6.1box@7.32,6.1build@10.97,6.1aloud@14.11,6.1kept@16.2,6.1new@19.86
 08    12.9      -  7.1box@2.39,7.1moved@5.26,7.1checked@10.03,7.1back@11.47
 09    11.4      -  5.1clear@0.91,5.1made@4.1,5.1cap@4.56,5.1url@10.03
7 sections with cues; 1 unresolved  (estimated words: times are placeholders)
error: 1 cue(s) could not be matched to the narration; a step whose cues are unresolved never appears. Fix the phrases in cues.json (see the notes above) or pass allow_unresolved=True / --allow-unresolved:
  section 03: 3.4name: phrase not found: 'gradient decent'

• The phrase has a typo.
• The script writes a number as words, and the phrase uses digits, or the other way around.
• The phrase uses another word form, such as “rates” for “rate”.
• A hyphen joins two words into one token.
• The phrase has a curly apostrophe. Matching removes it, but the spoken word keeps a straight one.

1. Open build/audio/NN-slug.words.json for the section.
2. Find the words as the voice says them.
3. Copy those words into the cue’s on value in cues.json.
4. Run decktalk beats.

​

not in its page in beats

                    ! 5.1cap: not in deck/index.html
7 sections with cues; 0 unresolved  (estimated words: times are placeholders)
error: 1 cue id(s) in cues.json appear nowhere in the page that plays them, so the page would never reveal them. Add data-cue="5.1cap" to the step in deck/index.html, fix the id in cues.json, or pass --allow-unknown:
  section 09: 5.1cap: not in deck/index.html

1. If the id has a typo, fix it in cues.json.
2. If no step uses the cue, add data-cue="<id>" to the element in the page.
3. If the page builds its cue ids at run time, pass --allow-unknown.

​

UNRESOLVED in beats or verify

• In beats --json, a note has the verdict UNRESOLVED when a phrase is not found or the section has no words.
• In verify, a cue named on the command line is not in beats.json. The row reads UNRESOLVED: the cue is not in beats.json.

1. If beats printed it, follow phrase not found in beats.
2. If verify printed it, check the SECTION:CUE spelling against build/audio/beats.json.
3. If the cue is new, run decktalk beats before verify.

​

UNKNOWN in beats

1. Follow not in its page in beats.

​

shorter than the visuals need in beats

1. If the slides need more time, add words or a [pause N] to the section in script.md.
2. If the slides are fine, lower or remove min_seconds in cues.json.

​

is past the end of the audio in beats

1. Reduce the cue’s offset in cues.json, or move the cue to an earlier phrase.

​

occurs N times in this section in beats

1. Compare the times in the note with the moment the visual should appear.
2. If a later match is right, set "occurrence" to its position, such as 2, in cues.json.
3. If the first match is right, set "occurrence": 1 to keep it and silence the note.
4. Or make the phrase longer, so it matches only once.

​

no words in beats

1. Run decktalk narrate again. For a rehearsal, run decktalk narrate --silent in a copy of the project.
2. Run decktalk beats.

​

is not in decktalk.toml in beats

1. If the key is a typo, fix it in cues.json.
2. If the section is new, add its [[section]] table.

​

preflight

​

NO CHANGE or THIN CHANGE? in preflight

1. Open the row’s two PNG files under build/preflight/NN/.
2. If the reveal is too small to see, make it larger or give it more contrast in the page.
3. If the reveal is small on purpose, mark the cue "verify": false. Or leave it, and check it by eye after the build.

​

RUNTIME_OUTDATED in preflight

1. Run decktalk runtime to copy the packaged runtime into the project.
2. Run decktalk preflight again.

​

record, measure, and check

​

PAGE ERROR in check

• A render template has a single backslash, such as \underline, which is a syntax error.
• The runtime <script> comes after the DeckTalk.scene calls.
• The page does not load decktalk-runtime.js.

1. Open the page in a browser with ?scene=N&hud=1.
2. Read the error in the browser console.
3. Fix the page.
4. Record the section again.

​

STALLED in check

1. Close other work, or use a less busy machine.
2. Record the section again.

​

TRUNCATED in check

1. Record the section again.
2. Run decktalk check.

​

NO COVER in measure or check

• The page removes the cover itself.
• A page written by hand starts its clock at load instead of at DeckTalk.startClock().

1. Make sure that the page loads the packaged decktalk-runtime.js.
2. If you upgraded DeckTalk, run decktalk runtime.
3. If the machine is very slow, raise [record] min_lead_seconds.
4. Record the section again.

​

BLACK? in check

1. Open the page in a browser with ?scene=N&hud=1.
2. If the page is blank, read the browser console and fix the error.
3. If the slide is dark on purpose, do nothing. BLACK? exits 1 only with --strict.

​

KATEX? in check

• data-tex could not be parsed: "<tex>". A backslash inside a render template is single.
• KaTeX did not load within 5 s, so [data-tex] elements stay plain text. The page loads KaTeX from a CDN, which fails offline.

1. If a value did not parse, write every backslash twice inside the render backticks.
2. If KaTeX did not load, run decktalk setup.
3. Run decktalk doctor and check that the katex row is ok.
4. Copy the cached katex directory that doctor prints into deck/katex/.
5. In deck/index.html, replace the two CDN tags with the local tags below.
6. Record the section again.

<link rel="stylesheet" href="./katex/katex.min.css">
<script src="./katex/katex.min.js"></script>

​

no narration span yet in record

1. If the heading is missing, add ## N. Title to script.md.
2. Run decktalk narrate.

​

A section is early or late by a fixed amount

1. If assemble printed STALE MEASUREMENT, follow STALE MEASUREMENT in assemble.
2. Open build/rec/NN-scene.json and read lead_method.
3. If it starts with NO COVER, follow NO COVER in measure or check.
4. Record the section again.

​

assemble

​

missing; slate for in assemble

section 05: media/edit-before.mov missing; slate for 4.36s (drop your clip at that path; the section is optional, so --strict allows the slate)

1. If you have the video, put it at the path in clip.
2. If the section sets optional = true, delete that line after the clip is in place.
3. If you do not want the clip, delete the section from both decktalk.toml and script.md.

​

clip missing or recording missing in assemble

error: section 5: clip missing: ~/clip-lesson/media/edit-before.mov. Put your clip at that path, or set optional = true on the section to play its slate under --strict.

1. If a clip is missing, put the video at the path in clip.
2. If you want the slate for now, set optional = true on the clip section.
3. If a recording is missing, record the section again.

​

using black in assemble

1. Record the section again.

​

STALE MEASUREMENT in assemble

section 04: STALE MEASUREMENT: build/rec/04-scene.webm was never measured, so the cut would trim the recorder's wall-clock estimate of 1.506s. Every reveal in the section may play early or late. Run `decktalk measure --only 4`, or pass --strict to stop on this.

1. Run decktalk measure --only N for the section in the message.
2. Run decktalk assemble.

​

has no span in in assemble

1. If the heading is missing, add ## N. Title to script.md.
2. Run decktalk build.

​

underscore missing in assemble

underscore missing (~/my-lesson/build/music/underscore.mp3); no music (`decktalk soundscape`)

1. If you want the sound, run decktalk soundscape or put your own file at the path.
2. If you do not want it, remove the key from [mix].

​

unresolved; skipped in assemble

1. If a marker is skipped, check its section and on values in the markers file.
2. If a sound effect is skipped, check that beats resolved its cue in that section.
3. Run decktalk assemble.

​

[loud] skipped in assemble

[loud] skipped: the narration is a silent placeholder, so there is no speech to normalize, and the clicks stay at -24 dBFS for the a/v check

​

true peak or integrated loudness in assemble

1. Lower the underscore, ambience, or sound effect levels in [mix].
2. Run decktalk assemble.

​

verify

​

BLACK in verify

1. Make sure that the scene’s first cued step draws something at t=0.
2. If a dip to black is long on purpose, raise [verify] after_dip_seconds.

​

SPEECH AT CUT in verify

1. Raise [narration] min_tail_seconds to add more silence after the last word.

​

POP AT CUT in verify

• The page opens in a different state than the previous page ended in, such as a step that is not shown yet.
• An element sits at a different position or size in the two pages.
• The previous section’s last step fires after its narration ends, so its recording ends early.

1. Run decktalk shots --section N --at 0 for this section, and compare it with the last frame of the previous section.
2. Make the page’s opening state match the previous page’s final state.
3. If the jump is intended, remove carries_previous from the section.

​

NO CHANGE in verify

• The reveal is very small or very slow.
• The reveal changes only color at the same brightness. verify compares luma only.

1. Run decktalk shots --section N --at S, where S is just after the value in the cue column.
2. If the reveal is subtle on purpose, mark the cue "verify": false in cues.json.
3. If the reveal is slow, lengthen [verify] probe_delays.

​

THIN CHANGE? in verify

1. Run decktalk shots --section N --at S, where S is just after the value in the cue column.
2. If the reveal is too small to see, make it larger or give it more contrast in the page.
3. If the reveal is small on purpose and plainly visible, leave it. Or mark the cue "verify": false.
4. To turn the warning off, set [verify] thin_change_factor = 1.

​

OFF CUE in verify

check                 cue       at   chg %   ctl %   offset     a/v  result
3:3.2way            22.17    58.65    1.00    0.00    -90ms  -118ms  OFF CUE

• A negative offset column means that something moved before the cue. Often an earlier reveal is still animating, or a data-at element appeared at the mount.
• A positive offset column of more than a frame or two means that the reveal has its own delay, such as a CSS transition.

1. Run decktalk shots --section N --at S for times around the value in the cue column.
2. Find the early motion or the delay in the frames.
3. If the delay is intended, raise [verify] max_offset_frames.

​

A large a/v value in verify

1. Build with decktalk build --silent --nomix to rule out the soundscape.
2. Open build/rec/NN-scene.json and check that lead_method starts with cover.
3. Record the section again.
4. Check that the offset column alone is small.

​

NO_CLICK in verify

​

skipped in verify

1. Find the reason in Skipped rows, and apply its fix.

​

malformed check in verify

1. Write each cue as SECTION:CUE, such as 8:7.1checked.

​

need build/out/NN-section.mp4 files in verify

error: need build/out/NN-section.mp4 files and the final mp4; run `decktalk assemble` first

1. Run decktalk build --silent, or decktalk assemble if the recordings exist.
2. Run decktalk verify.

​

is not a section in decktalk.toml in assemble or verify

build/out/04-section.mp4 is not a section in decktalk.toml, so verify ignores it. Delete the file if an earlier build left it.

1. If you renumbered or removed the section, delete the file.

​

A typewriter reveal fails the cue check

1. Give the element’s container a reveal that appears at once on the same cue, such as data-fx="fade".
2. Keep data-type or data-sync on the text inside it.

​

words and clip

​

timeline.json not found in words or clip

error: ~/my-lesson/build/audio/timeline.json not found. Run `decktalk narrate` first.

1. Run decktalk narrate, or decktalk build --silent.
2. Run the command again.

​

has no section video in clip

error: section 1 has no section video at ~/my-lesson/build/out/01-section.mp4. Run `decktalk assemble` first.

1. Run decktalk build --silent, or decktalk assemble if the recordings exist.
2. Run decktalk clip again.

​

is a clip section in clip

error: section 5 is a clip section; cut a clip from a page section

1. Run decktalk status. Each page section row names its page, and each clip section row starts with clip.
2. Run decktalk clip with the number of a page section.

​

cuts the word in clip

section 01: the span cuts the word 'ball.' in two, so the words file leaves it out

1. Run decktalk words --only N for the section.
2. Move --from before the word’s start, or --to after the word’s end, into the silence next to the word.
3. Run decktalk clip again.

​

Pages in a browser

​

data-sync text not found in the spoken words in a page

1. Compare the element’s text with the sentence in script.md.
2. Make the words match. Case and punctuation do not matter.

​

matches no element, handler, or step in a page

[page] 09-scene  cue "5.1cap" matches no element, handler, or step

1. Add data-cue="<id>" to the element that should appear.

​

unknown cue id in a page

1. Check the id against the step ids and their cues lists.
2. Add the id to the cues list of the step that should own it.

​

owns no cue in a page

1. Add a cue for the step to cues.json.

​

A page is empty, or window.__decktalk is missing

1. Load decktalk-runtime.js before any DeckTalk.scene call.
2. Open the page in a browser to check the scene index.

​

Speed

​

A build is slow

1. If you changed one section, run decktalk build --only N.
2. For drafts, set DECKTALK_VIDEO_PRESET=veryfast, or preset = "veryfast" under [video].
3. For the final video, go back to the default preset.

​

TimeoutError in shots

error: TimeoutError: Page.wait_for_function: Timeout 30000ms exceeded. (add -v for the traceback)

1. Use --at values of 30 s or less.
2. For a later moment in a long section, take a frame from the final video instead.

​

Related

• Look up an option or exit code: CLI
• Read a verify table: verify
• Ask a general question: FAQ