Failure modes → fix
The scene mistakes that happen most often, their cause, and a short fix.
For problems with the app itself (selection, locks, keys, export), see Troubleshooting. Words like clock, period and ease are in the glossary.
Where a mistake shows
Starlight checks a scene file each time it loads it. A mistake in the file shows as a message.
- After File › Reload Project from Disk (⌘R / Ctrl+R), or when Claude or another program changes the open scene: a red line at the bottom left of the canvas. For example: scene 03-touchdown: comps.main.0.fill — unresolved token $primary — showing its last good version. The canvas keeps the last version that loaded.
- When you open a scene from the scene list (or with ⌘PageDown / Ctrl+PageDown and ⌘PageUp / Ctrl+PageUp): the canvas keeps the scene you had before, with its unsaved edits. The red line says why, for example scene 02-walls: Map keys must be unique at line 3, column 1 — 01-main stays open.
- When the project opens: if the scene you had open last is broken, Starlight opens the project's default scene instead. If that one is broken too, it opens the first other scene that works. The red line says which, for example … — opened 01-main instead. So the next launch never gets stuck on a broken scene.
- Only when no scene opens, or
project.yamlhas a mistake, the middle of the canvas shows error — and the message, and no surfaces show.
The message names the file, the place in the file, and what is wrong. Read an error message explains the place, for example comps.main.0.fill.
- Fix the file in your text editor, and save it.
- In Starlight, press ⌘R / Ctrl+R again.
- The red line goes away when the scene loads without a mistake, or when you save the scene.
- The line shows one mistake. If the file has more, it ends with the number of the others, for example (+2 more). The full message is in the log (Send diagnostics).
- Common messages: Read an error message, and More messages from the scene file below.
Loops and motion
Problems with animation and with the loop point.
| Symptom | Cause | Fix |
|---|---|---|
| A belt jumps or shows a seam at the loop point | The belt's drift is not a whole number of gaps per loop. | Make drift × loop = N × gap. |
| Motion stutters at the loop point, and the clock is amber | The clock's period does not divide the scene loop. | Pick a period that divides it: 2 s into 4 s, not 3 s. |
| A triggered clock jumps at the loop point. Properties says starts (trigger / offset) off a whole cycle — seam at export | The cue that starts it is not on a whole cycle of the clock's own period. | Move the cue. For example, a 1 s clock in a 4 s loop can start at 1 s (phase 0.25), not at 1.2 s (phase 0.3). |
A pingpong snaps back at the loop point | One round trip takes twice the period. A period equal to the loop gets only halfway. The clock shows the amber loop-seam warning. | Give it half the loop. |
| A spin slows down at every turn | The short form [0, 360] eases in and out. | Use rotate: [{ value: 0, ease: linear }, { value: 360 }]. |
A once clock never finishes | Its period is longer than the scene loop, so the loop starts it again first. | Make the period equal to the loop, or shorter. |
| A cascade pulses all at once | The clock is inside the cloned comp. stagger only offsets the cloner's own clock. | Move the clock onto the clone node. |
| A cascade does not move at all | The clock: is written inside the clone: { } map, where Starlight ignores it. | Write clock: beside clone:, at the same indent. |
| A pop looks soft | The hit uses smooth or ease. | Use snap for the hit and overshoot for the settle. |
Surfaces and layout
Problems with size and position on the surfaces.
| Symptom | Cause | Fix |
|---|---|---|
| Marks on a ribbon are tiny, in dozens of tiles | tile-x shrank the 1080-px-tall design to the ribbon's 84 px. | Give the ribbon its own design: 1920x84 and a comp made at that height. |
| A shape or text does not move | position is written on the layer itself. Starlight ignores it there, with no message. | Put the layer inside a transform, and set the position there. |
unknown comp "x" — valid comps: … | A use: names a comp that does not exist, often a typing mistake. | Use one of the comps in the message. |
"x" names no comp and is not an asset path … — valid comps: … | A clone's of: names no comp. A file path needs its extension, for example assets/logo.svg. | Use a comp from the message, or the full file path. |
comp cycle a → b → a — a comp cannot instance itself … | Two comps place each other, or a comp places itself. | Remove one of the use: (or clone) lines in the cycle. |
| A surface is black | No comp feeds it (no use:), and it has no layers of its own. | Give the surface use: <comp>, or wire a comp to it in the node graph. |
Colour, type and media
Problems with colours, fonts and files.
| Symptom | Cause | Fix |
|---|---|---|
unresolved token $x | The token is not in the scene theme or the brand kit. | Add the token, or use a colour like "#ff8800". Keep the quotes: without them, # starts a YAML comment. |
expected a colour … (got nothing — quote a hex colour …) | A hex colour has no quotes, so YAML read it as a comment. | Write fill: "#ffffff", with the quotes. |
| Text shows in a condensed system font, not the brand font | The font file that brand.fonts names is missing. | Put the .otf, .ttf, .woff or .woff2 file at that fonts/ path. Or drop a font file on the window, and pick its family in Properties. The font row's ↻ button finds new files in fonts/. |
| A layer does not show, also in exports | Its file is missing, cannot be read, or is online-only in Dropbox. Starlight draws nothing for it (one white pixel). The line at the bottom left of the canvas names the file: missing media: … or could not load: …. | See Find missing media and Online-only files. |
More messages from the scene file
What more messages mean. Each one comes after the file and the place, for example scenes/01-intro.yaml: comps.main.0.clock — unknown ease "bouncy". The most common ones are in Read an error message.
| Message | Cause | Fix |
|---|---|---|
Map keys must be unique at line N, column M | The same key is in the file twice, often a second comps: or loop: from a pasted recipe. | Join the two blocks under one key. |
unknown ease "x" … | The ease name is misspelled. | Use a name from Eases, steps(n) or cubic-bezier(…). |
unknown animatable property "x" | A track names something a clock cannot move. | Use x, y, scale, scaleX, scaleY, rotate, skewX, skewY or opacity. |
mode must be once, loop, or pingpong | The clock's mode is misspelled. | Use one of the three. |
a clock with use: "x" takes its period and mode from that named clock … | The clock names a shared clock and also has its own period or mode. | Remove the period and mode, or remove use:. |
this scene is schemaVersion N, written by a newer Starlight … | A newer Starlight saved the file. | Update Starlight on this computer. |
- The full list of messages is in
docs/scene-format.md, section 11, in the Starlight source. - A misspelled key that is not a layer kind gives no message. Starlight keeps it and ignores it. If a change does nothing, check the spelling.