Skip to Content
Starlight

Troubleshooting

What a message or a strange result means, and the steps to fix it.

Mistakes in scene YAML are in Failure modes. Export errors are in When an export fails.

Selecting and editing

Problems when you click, select or animate layers.

SymptomCause and fix
A click on the canvas selects the whole surface or comp, not the layerA click selects at the node graph's current level. To reach a layer inside a comp:
  1. Double-click the comp in the node graph.
  2. Click the layer on the canvas.
See Select a layer.
My selection went away when I changed graph levelWhen you go into or out of a comp, Starlight deselects what that level does not show.
The selection is a box with no handlesYou selected the content, and a transform places it. Drag the box: it moves the transform. Or click the layer on the canvas, which selects the transform.
A position: on my text does nothingOnly a transform sets position. Put the layer inside a transform.
curves: select an animated layer firstThe timeline's curves view shows the selected animated layer. Select one. Or use the layers view: ⌥T / Alt+T switches views.
A clock is amber in the node graphIts period does not divide the scene loop. Pick a period that does.

The canvas is frozen, black or shows an error

Use these steps when the canvas stops moving, goes black, or shows This view hit an error.

  1. Press Space. The scene may only be paused (paused · space to play).
  2. Look at the canvas's top right. Focus or a generation preview hides the other surfaces. Press f to leave focus. Click × or press Esc to close a preview.
  3. If a box says This view hit an error, click Reload view. Starlight keeps your unsaved edits as a recovery draft first.
  4. If the canvas is still frozen or black, choose Help › Troubleshooting › Force Reload App (⇧⌘R / Ctrl+Shift+R).
  5. Click Force Reload. The project opens again from disk.
  6. A card in the lower left of the canvas offers your unsaved changes. Click Restore my changes to get them back.
  • Force Reload App works even when the app does not respond to other keys.
  • The error box also has Reload app and Reveal logs.
  • When the surfaces go black because of a graphics card error, Starlight rebuilds them by itself. It tries up to three times in a session. If they stay black, use Force Reload App.
  • When the whole canvas stops because the graphics card was reset, Starlight rebuilds the canvas by itself. See The graphics card was reset.
  • A red line at the bottom left of the canvas names a mistake in the scene file. See Where a mistake shows.
  • If it happens again, send diagnostics.

The graphics card was reset

Sometimes the graphics card stops for a moment: its driver resets, or it runs out of memory. Then the canvas stops too. Starlight gets the canvas back by itself. This is what happens:

  1. The canvas stops moving.
  2. Starlight keeps your unsaved changes as a recovery draft.
  3. After a few seconds, the window loads again. The project opens from disk, on the same scene.
  4. A message says: The graphics card was reset. The canvas was rebuilt. Click its ✕ to close it.
  5. If you had unsaved changes, a card in the lower left of the canvas offers them. Click Restore my changes to get them back.

If the graphics card fails 3 times in 5 minutes, Starlight stops trying. It says The graphics card keeps failing. Then:

  1. Click Restart Starlight.
  2. If you have unsaved changes, Starlight asks you to save them. Click Save.
  3. Starlight closes and opens again.
  • The Claude panel keeps its sessions while the window loads again.
  • A running export stops. Start it again after the canvas is back.
  • On a laptop with two graphics chips, use the fast one: open Settings › Appearance and check that graphics chip is high performance. On the slow chip the graphics card resets more often.
  • Update the graphics driver from the maker of the chip (NVIDIA, AMD or Intel).
  • If it keeps happening, send diagnostics. The log has a line for each reset and each rebuild.

Saving, opening and sharing

Messages about files, projects and other artists.

SymptomCause and fix
A card in the lower left: Starlight closed before your changes to "<scene>" were saved.Starlight closed, crashed or reloaded with unsaved changes. Starlight kept them as a draft on this computer. Click Restore my changes to get them back, Keep saved version to delete the draft (it asks first), or Later to decide later (Get unsaved edits back).
The Projects screen says Starlight couldn't open your project, with the errorRead the error. Fix the cause, then click retry. copy error copies the message, for example to send it to the person who helps you. You can also open another project from the list.
Open Project says a folder holds 3 projects … open one of themPick the project folder itself: the one with project.yaml in it. Or pick the project.yaml file.
"x" isn't a Starlight project: there is no project.yaml in itYou picked a folder that is not a project, or a folder inside one. Pick the folder that holds project.yaml.
project.yaml is online-only in Dropbox and did not download in time …Dropbox has not downloaded the project yet. It keeps downloading in the background. Wait a moment, then open the project again.
Usually on a Mac: the Projects screen says Starlight was blocked from reading your project folderThe system blocked the folder.
  1. Open System Settings › Privacy & Security › Files & Folders.
  2. Allow Starlight to use your Documents folder.
  3. Click retry.
Or open the folder with File › Open Project….
SAVE FAILED — …Starlight could not write the scene file. The message stays until you click its ✕ (Messages). Check that the disk has space, and that Dropbox is running in a shared project. Then press ⌘S / Ctrl+S again. Your edits stay in the app, and in the recovery draft.
Dana is editing 02-walls — read-only here. My edits are undone, and save is refused (read-only — … save a copy, or take it over from the lock)Another artist has the scene's edit lock. Ask them to unlock it, or click edit anyway. save as a copy keeps edits you made before the lock arrived (Edit a scene someone else has).
restore failed — read-only — Dana is editing 02-walls; not written until they unlock itIn a shared project, the version you restore holds a scene that another artist has locked. Starlight changes nothing. Ask them to unlock the scene, then restore again.
Another artist changed "02-walls" (Dropbox sync) while you have unsaved changes. with Reload and Keep mineTheir save arrived while you had unsaved edits on that scene. The message says deleted or renamed if they removed or renamed it (When another artist saves).
Another program changed "02-walls" on disk — checkpoint … — while you have unsaved changes.Another program saved this scene, for example a version restore or a finished upscale. Reload takes its version. Keep mine keeps yours (Undo Claude's change). Claude's normal edits do not show this bar: they go into the open scene as one undo step.
Another program changed "02-walls" on disk. It has unsaved changes here. with Reload and Keep mineA scene that you left with unsaved edits changed on disk. Reload takes the disk version (open the scene and press ⌘Z / Ctrl+Z to get your edits back). Keep mine keeps yours (Undo Claude's change).
N Dropbox conflicted copies — choose a versionTwo computers saved the same file before it synced.
  1. Click review.
  2. For each copy, click keep mine or use theirs.
See Resolve a conflicted copy.
A scene in the scene list says downloading…In a shared project, the scene file is still online-only on this computer. It opens when Dropbox has downloaded it.
An asset shows ☁, or a layer does not showThe file is online-only in Dropbox (Online-only files), or missing (Find missing media). A missing file draws nothing. The canvas names it at the bottom left: missing media: ….
A line at the top: this project runs its own code … trust them?The project has extensions. See Trust a project's extensions.
extensions not loaded — trust them later from the paletteYou clicked not now, so the project's extensions do not run. To trust them later, open the command palette (⌘/ / Ctrl+/) and choose trust project extensions….

Online-only files

Dropbox can keep a file only online, to save disk space. Starlight cannot use that file until it is downloaded.

Signs of an online-only file:

  • a ☁ badge on an asset;
  • a layer that does not show, also in exports;
  • the Assets panel notice N linked files online-only: …, or in a shared project N project files online-only: …;
  • a notice when the project opens: N linked files this project uses are online-only — Assets → make available offline;
  • on the Projects screen, online-only in Dropbox · opening downloads it.
  1. Open the Assets panel (⇧A / Shift+A).
  2. In the notice, click make available offline. For one file, right-click its tile and choose Make Available Offline.
  3. Wait until the download finishes. The notice shows making available offline 3/12, then made available offline: 12/12. The badge changes from ☁ to ○ (downloaded) or ● (ready in the media cache).
  4. On a Mac, right-click the folder in Finder and choose Make available offline. This keeps the files on disk.
  • On a Mac, Starlight downloads the files but cannot pin them (keep them on disk). Without step 4, Dropbox may remove them again later.
  • On Windows, Starlight pins the files, so they stay.
  • To stop the downloads, click stop in the notice. Files that are already done stay on disk.
  • A download that fails (for example, with no internet) does not try again by itself. The notice says · N failed. Click make available offline again.
  • Two more badges: ✕ means the file is not on this computer at all. ? means the check took too long. Click rescan in Settings › Media.
  • A generation that uses an online-only input stops with an error. Download the file first.

Keys, AI, Glimpse and export

Messages from Settings › Keys, ⌘K compose, Generations, the Glimpse panel and the export sheet.

SymptomCause and fix
Settings › Keys: that key didn't work — …Starlight could not check the key with the service. This usually means no internet, or the service has a problem. It does not mean a bad key. Connect, then paste the key again.
Settings › Keys: … rejected that keyThe key is wrong or no longer valid. Copy it again from the provider's website.
Settings › Keys or Generations: … site blocks this connection (Cloudflare, Ray ID …)The provider's website blocks your connection. Your key may be fine. See Blocked connection.
Settings › Keys: secure key storage is unavailable here — set … in the environment insteadThis computer has no safe place to store keys for Starlight. Set the environment variable that the message names, for example ANTHROPIC_API_KEY, then start Starlight again.
Generations: … is online-only — make it available offline firstAn input file of the job is not downloaded. Download it in the Assets panel (Online-only files), then make the job again.
Glimpse panel: could not load the venue, with its addressStarlight could not download the 3D room. Check your internet connection, then click retry (Open Glimpse).
Glimpse panel: no surface named … or "panorama" — the walls stay darkNo surface in the project has the name of a wall in the venue. Use the venue's wall names (What the walls show).
⌘K compose (⌘K / Ctrl+K): Claude Code is not installed on this computer⌘K sends your words to the Claude panel, so it needs Claude Code. The Claude panel shows the install command. Install it, then press ⏎ / Enter in the bar again (When Claude does not start).
⌘K compose: Claude is busy. Your request goes in when it finishes.Nothing is wrong. Claude finishes its work first, then gets your request. The other waiting lines work the same way (Compose a change).
⌘K compose: Claude isn't ready in tab 1: click the tab, then try again.Claude runs in that tab, but Starlight did not see its prompt for 20 seconds. Your words are still in the bar. Click the tab in the Claude panel and look at it: close a menu or a dialog there, or answer a question. Then press ⌘K / Ctrl+K and ⏎ / Enter again.
⌘K compose: Claude did not start. or Claude looks stuckStarlight waited 20 seconds for Claude's prompt. Your words are still in the bar. Open the Claude panel with ⌃` / Ctrl+` and look at it: answer a question there, or wait for the prompt. Then press ⌘K / Ctrl+K and ⏎ / Enter again (When Claude does not start).
⌘K compose on the openrouter planner names the key it needsClick its button. It opens Settings › Keys. Paste the OpenRouter key there.
Export sheet: libx265 is software — slow at 6400 pxHEVC (H.265) is a video format. This computer has no hardware HEVC encoder, so HEVC runs on the CPU. It works, but slowly (Which encoder runs).
Any other export messageSee When an export fails.
Something else is wrongSend diagnostics to the person who helps you.

Blocked connection

Some providers use a security service called Cloudflare. Cloudflare can block a connection before the provider sees it. Then Starlight says, for example:

Atlas Cloud's site blocks this connection (Cloudflare, Ray ID a51c3c1bea7b5bac). This is often by country or network: try another network, or ask Atlas Cloud support. Your key may be fine.

  • In Settings › Keys, the row says stored · not checked, with a yellow dot and this message in red. A key that you paste now is not stored, because Starlight could not check it.
  • In Generations, the line says error · site blocks this connection. Hover the line, or look at the card, for the whole message.
  • The block is about your connection: your country or region, your network, or a VPN. It does not mean that your key is wrong. Do not make a new key.
  • If the message says the country or region this connection comes from (Cloudflare error 1009), the provider does not accept connections from your country or region.

What to try:

  1. Use another network. For example, a phone hotspot or another Wi-Fi. If you use a VPN, turn it off, or turn it on.
  2. Open Settings › Keys again. If the row shows the balance, the connection works. Click retry on the failed job.
  3. If it is still blocked, write to the provider's support. Copy the Ray ID from the message into your email. The Ray ID helps them find the block.
  4. Or use another provider for the same model. Seedance 2.5 is also on Magnific, videorouter and Higgsfield. Add that provider's key in Settings › Keys. Then make the job again with that provider.

Send diagnostics and find the logs

Diagnostics is one zip file with the app's logs. Send it to the person who helps you with a problem.

  1. Choose Help › Troubleshooting › Export Diagnostics…. Or open Settings › Diagnostics and click export diagnostics….
  2. Pick where to save the zip. Starlight suggests your Desktop (or Downloads) and a name like Starlight-diagnostics-20261018-2058.zip.
  3. Click Save. Starlight shows the file in Finder (Mac) or Explorer (Windows), and a box says Diagnostics exported.
  4. Send the zip by email or chat.
  • The zip holds the logs, any crash reports and a summary of your system (app version, OS, GPU, ffmpeg). It holds no project files, media or keys. Starlight removes keys and tokens from the logs it puts in the zip.
  • The zip holds the 20 newest crash reports, each up to 50 MB. The box says how many it left out.
  • Starlight never uploads anything. You decide who gets the file.
  • Reveal Logs and Export Diagnostics… work even when no project opens. Starlight Help and Show Skills Folder need an open project.
  • If the zip cannot be written, a box says Export Diagnostics failed and gives the reason.

Open the logs folder: on a Mac choose Help › Troubleshooting › Reveal Logs in Finder; on Windows choose Help › Troubleshooting › Show Logs in Explorer. The files are here:

FilesMacWindows
Logs~/Library/Application Support/Starlight/logs/%APPDATA%\Starlight\logs\
Crash reports~/Library/Application Support/Starlight/crashes/%APPDATA%\Starlight\crashes\
This computer's data: the media cache and shared projects~/Library/Application Support/Starlight/%APPDATA%\Starlight\

The live log is starlight.log. At 5 MB it moves to starlight.1.log, and Starlight keeps up to five files.

Windows: where your data is

On Windows your data is in %APPDATA%\Starlight. Updates never touch it.

That folder holds your settings, keys and logs, the media cache, and for each shared project: its version history, pre-renders, layout, Claude tabs, generations and MCP token. Renders that Starlight 0.2.34 or older made for a shared project are there too (Where the files land).

  • Before 0.2.29, the media cache and the shared projects were in %LOCALAPPDATA%\Starlight. The installer uses that folder too, and each install emptied it. So after an update, videos were prepared again, and shared projects lost their Claude tabs and history on that computer.
  • To install 0.2.29, double-click Install Starlight.cmd next to the setup file. It copies your projects and media cache to %APPDATA%\Starlight, then starts the installer. It only copies. It deletes nothing.
  • When Starlight starts, it also copies anything that is still in the old folder. It never replaces a file that is already in %APPDATA%\Starlight. The log says what it copied.
  • Your Claude chats stay. If a project's tabs are gone, right-click in the Claude panel and pick resume an earlier chat… (Resume an earlier chat).
  • Uninstalling Starlight keeps your data. To remove it, delete the folder yourself.

To open the folder: press Win+R, type %APPDATA%\Starlight and press Enter.

On this page