Troubleshooting¶

Common problems on site, what each message means, and how to fix it.

Your device isn't connected to the show machine. The sign-in card appears only while the connection is live, so this is a network or show machine problem, not a password problem.

The same screen also appears later if the show machine stops answering: straight away from the activation screen, and after 8 seconds anywhere else, including the main interface. It doesn't mean the license has ended, and Moonshine goes back to where you were as soon as the machine answers.

To fix it:

Check that Moonshine is running on the show machine. When it is, the show machine's own screen shows a frame rate and an address. See The show machine's screen.
On a second device, check that it's on the same network, and open the exact address from the Share Moonshine panel. An address typed from memory is the most common cause. See Join from another device.
If the screen shows The server is not answering with a Retry button, press it once the machine is back.

A red box appears with a message¶

The show machine refused the sign-in, and the box shows its reason. Every message is listed in First launch.

Type the username and password again; both are case-sensitive. After five wrong passwords in five minutes, that username has to wait before it can try again, and the message says for how long. If you're sure the details are right, an administrator can reset the password in Settings → Admin → Users, or create a new account there with Add User.

Nobody knows the admin password¶

Reset the accounts on the show machine itself. Only an administrator can reset a password in Moonshine, so if the only administrator has forgotten theirs, you have to start the accounts again from scratch:

Close Moonshine. If Owlette manages it, stop it in Owlette first, or Owlette restarts it while you work. On a Mac, stop it by running launchctl bootout gui/$(id -u)/software.moonshine.server in Terminal; logging out and back in starts it again.
Open the data folder. On Windows, choose Start → Moonshine → Moonshine data folder (C:\ProgramData\Moonshine\data on a default install). On a Mac, it's /Users/Shared/Moonshine/data.
Move users.json, users.json.bak and users.json.bak2 out of the folder. Move all three: Moonshine rebuilds a missing users.json from the backups, so moving only the first brings the old accounts back. Move the three sessions.json files too, so no old sign-in remains.
Start Moonshine again and connect. With no accounts, the machine shows First-time setup. Create the new administrator there (see Setting up a new machine). Until you do, whoever connects first gets that screen, so keep other people off the show network while you do this.

This removes every account, not only the administrator's. Recreate the others in Settings → Admin. Projects, media, the license and the certificate aren't affected. Keep the moved files until you're sure you don't need them.

Someone signed in with your account somewhere else, or your sign-in expired. Each account can have one session at a time. Signing in as the same user in another tab or on another device ends the earlier session, and that screen goes back to sign-in without a message. A remembered sign-in also ends two weeks after it started, and the sign-in card then reads Session expired.

Continue in the newer window, or sign in again here, which ends the other session. If several people work at once, give each person their own account. See Users and sessions.

Moonshine is asking for a license key¶

The show machine has no working license. The screen reads Moonshine Server license has ended when the license has run out, or Activate Moonshine Server when the machine holds no working license. This screen appears before the sign-in screen, so you can license a machine before anyone signs in. A line under the heading names the show machine and often the reason. See Why the screen is up.

To activate:

Type or paste your key into License key. The field switches to upper case, so capitalization doesn't matter.
Press Activate. The button reads Activating… while it works, and the screen closes by itself once the machine is licensed.
If you don't have a key yet, use Join the free beta or buy Moonshine at the bottom of the panel. They open Tridant's sign-up or checkout in your usual browser. The beta key is valid until January 2, 2027. You can also email support@tridant.io.

If activation fails:

Message	What to do
The message returned by the server, or Activation failed. Please try again.	Check the key for typos, including the dashes. The key must be for Moonshine: a key for another Tridant product won't activate it.
Cannot reach server. Check that the backend is running and try again.	Activation needs the connection to the show machine. Restore it and try again.
Lost connection to server during activation. Please try again.	The connection dropped during activation. Try again once it's back.

Every activation message, and what to do about it, is in Install and activate.

While a trial or beta license is running, a strip across the sign-in screen names it and has a Buy Moonshine link. You can dismiss it for the session. In this version it usually shows no day count, because the show machine doesn't yet receive the end date from the license server. Once it does, the last two weeks of any license are shown on the sign-in screen and in the interface, with the date and the days left. See Trials and beta licenses.

The outputs show "This machine's Moonshine license has ended"¶

The license has ended or, if the card reads Moonshine is not licensed on this machine, the machine holds no working license. Every output shows the card instead of the show, playback stops, and every browser shows the activation screen.

Enter a key on any connected device. The card leaves every output as soon as the key is accepted. Playback doesn't restart by itself, so press play. See When a license ends.

Everything works except the video preview¶

The live preview needs a secure address and a device that can decode the video. Every control works without them, but the preview doesn't. A badge on the preview tells you what's missing.

Will the video preview work here? covers every badge and its fix, including the case where the connection is fine but the device can't decode the video.

Badge	What it means	Fix
Live preview unavailable — use localhost or https	You opened the plain address, which needs no setup.	Open the secure address from the Join tab of the Share Moonshine panel.
Live preview unavailable — this device doesn’t trust the show machine yet	You're on the secure address, but this device hasn't been through first-time setup.	Click Fix → on the badge, follow the steps for your platform, then reload.
Live preview unavailable — import the Moonshine certificate into Firefox	Firefox keeps its own certificate store.	Import the certificate into Firefox itself. A per-site exception isn't enough. The Fix → page has the steps.
Live preview unavailable — this browser can’t decode it	The browser or the graphics hardware can't decode the stream.	Try Chrome or Edge on that device. Retrying in the same browser won't help.
Hardware video decoding is off — restart Moonshine	In the desktop app, after a graphics fault, hardware video decoding stays off until the app restarts.	Quit Moonshine and open it again.
Live preview unavailable — retrying in 30s	Several attempts in a row failed, and Moonshine is waiting before it tries again.	Wait, or press Retry on the badge to try now.
Live (a small, dim green dot)	The preview is live: the show as the show machine draws it. Hover over it to see how long ago the last new picture arrived. It isn't any one projector's output, so a test pattern on one projector doesn't appear in it.	Nothing to do.
Live preview paused — no new picture	The connection is open, but no new picture has arrived for a few seconds. Moonshine reconnects by itself after 8 seconds.	Wait a moment. If it keeps coming back, check the show machine.
Loading live preview…	The preview is starting.	Wait a moment.
Reconnecting live preview…	The preview dropped, and Moonshine is reconnecting it.	Wait a moment. If it lasts, check that the show machine is still running.

To set a device up once: on a device that's already connected, click the QR code button in the top bar to open Share Moonshine, switch to First-time setup, and scan that code with the new device. Install the certificate as instructed, then switch back to Join and scan that code. From then on, the device gets video every time. For the full walkthrough, see Join from another device.

The plain address is still useful

The share panel offers it as the control-only option that needs no setup. If a colleague only needs to trigger playback from a phone, it's the quickest way to get them working.

A cuelist won't play¶

The cuelist isn't linked to a surface. Pressing play shows a warning like "Show Loop" isn't linked to a material in the scene graph — it won't play back. Link it to a Material node first., and nothing starts, because the cuelist has nowhere to show its picture.

Link the cuelist to the Material of the surface that should show it, then press play again. See Putting media on a surface and The scene graph.

The same check applies to next, previous and jumping to an item from the transport's list. If the warning appears on any of them, link the cuelist.

A control is dim and won't respond¶

Someone else is editing that area. Moonshine locks an area to you when you open a projector, the warp editor, the mask editor, the Cue tab, the Control tab or a page of Settings, and keeps the lock until you move on. While another person holds a lock, the panel is dimmed and a strip reads (their name) is editing.

Click Request access on the strip. The other person gets a message, (your name) is requesting edit access to …, with Grant and Deny buttons.
If they grant it, the panel becomes available to you.
If you'd rather not interrupt, work on a different projector. Most locks are per projector, so two people can work on two projectors at once. The Warp tab is the exception: whoever has it open on a surface holds every projector on that surface.

You may also see the error Couldn't update - (name) is editing this. It's the same situation: your change arrived a moment after someone else took the lock, so it was rejected. Make the change again once you hold the lock.

When you hold a lock, the strip turns green and shows a padlock button. Click it to Release lock early instead of waiting for it to release automatically. See Locks.

Nothing is coming out of a projector¶

Check these in order. The most common causes come first.

Is the output enabled? A new projector's output starts switched off. Each projector's card has an output pill reading Output: On, Output: Off or Output: — (no output at all) that you can click, and the output card in Projectors → Outputs has an Enabled switch. See Outputs.
Is it on the right monitor, in the right place? Check Monitor, Origin X and Origin Y. The Outputs view shows a warning when two enabled outputs overlap on one monitor, because one covers the other. The show machine's own screen lists every output and every unused display. See The show machine's screen.
Is the shutter closed? In the projector's Settings, the Shutter switch shows Open or Closed beside it. Closed shows black. Open · projector shutter closed means the projector's own shutter is closed although Moonshine is sending the picture: close the switch and open it again.
Is a test pattern on? In Projectors → Test Pattern, set it back to Off. A test pattern replaces your content on the surface. See Test patterns.
Is anything routed to that surface? A surface with no media, or with a cuelist that was never linked, shows nothing. See A cuelist won't play.
Does every output show a license card? Then the license has ended. See When a license ends.

If the Outputs view says it's still waiting for display information, Moonshine hasn't yet heard which monitors the show machine has. Give it a moment. If the message stays, the show machine hasn't finished starting.

After a restart, the alignment went back¶

When a project opens, each surface comes back in its last baked shape, so edits made after the last bake are lost. See Baking and reverting.

Redo the lost edits, or move a point so the newer shape in the 3D view reaches the projectors again. Then press Bake Warp. From now on, bake at the end of every alignment pass.

A file I dropped never appeared¶

Moonshine doesn't accept that file type. Unsupported files are ignored without a message: no item appears and no error is shown.

Check the extension against Supported file formats. The most common surprises are .tif, .exr and .avi, which aren't accepted. A .gltf is accepted, but it appears in the scene as a placeholder box and no projector draws it, so export it as .glb.

Do I have to save?¶

No. Moonshine saves as you work, and there's no save command or shortcut. An amber dot appears in the top bar while changes haven't been written yet; hover over it for the details. No dot means everything is saved.

Dot	Meaning
Amber, pulsing	Changes are being written (Saving…)
Amber, pulsing, with a bake message	Saved, but 3D surface edits aren't baked yet. The projectors show them now, but the surface goes back to the last bake when the project next opens
None	Everything is written, or nothing has changed yet

The only step that isn't automatic is baking a warp. Sculpted edits reach the projectors and are saved as you work, but Bake Warp makes them the shape the show machine restores when the project opens.

How do I restore a project?¶

It depends on what you're restoring from: a project you downloaded, a snapshot of a project that's still on the show machine, or a snapshot of a project whose folder is gone.

From a project you downloaded (with the download button in the Projects browser):

Close Moonshine on the show machine.
Open its data folder: C:\ProgramData\Moonshine\data on Windows (Start → Moonshine → Moonshine data folder), /Users/Shared/Moonshine/data on a Mac.
Unzip the file there. It holds one folder, named with the project's id, which goes beside the folders already there. If a folder with that name already exists, it's the same project: move it somewhere else first, so you can go back to it.
Start Moonshine. The project is in the Projects browser, with all its media.

The same zip opens on any other show machine in the same way, which is how you move a show between machines.

From a snapshot of a project that's still in the Projects browser:

Open the project, then Settings → Project → Snapshots.
Press Restore… beside the time you want to go back to, then Restore to confirm.

The project's setup goes back to that time for everyone working on it, and its media stays as it is. Files the snapshot doesn't include are moved to the project's trash. Moonshine first saves the current state as a snapshot, so to undo the restore, restore that one. See Snapshots.

From a snapshot of a project that's no longer in the Projects browser (its folder is gone), by hand:

Close Moonshine on the show machine.
Open the folder shown in Settings → Admin → Server → Snapshots, then open the zip from the time you want to go back to. Its name is that time in UTC, for example moonshine-2026-10-14_1945.zip.
The zip holds a folder for each project, named with the project's id. The project's name is in that folder's project.json.
Copy the project's folder from the zip into the data folder. Snapshots don't include media, so put the project's assets folder back from your own backup or a downloaded copy.
Blend layers aren't in the zip, and you can leave them out: Moonshine calculates them again when the project opens. To restore them anyway, look them up in the zip's manifest.json, which lists where each one goes and its file in the blobs folder beside the zip. Copy each one to where it goes, under the file name the path ends with.
Start Moonshine.