Troubleshooting

Fixes for common Loomscreen problems: launch and Gatekeeper, blank or paused wallpapers, playlists, imports, Workshop, overlays and updates.

Find your problem in the tables below. Each row lists what to check and how to fix it. If nothing here helps, see Still stuck?

Install and launch

Problem	Check	Fix
“Loomscreen.app is damaged” or “can’t be opened”	Gatekeeper may block the non-notarized build. This message alone does not prove the cause.	Verify the DMG checksum, then run the Lite or Pro command in If macOS refuses to open the download. If it persists, collect the launch error.
Menu bar icon is missing	Is the app running? Check Activity Monitor. Is the menu bar crowded?	Relaunch from `/Applications`. Check login-item restrictions.
App will not launch at all	Are you on macOS 14.6 or later? Pro also needs Apple Silicon.	On an Intel Mac, use Lite; its Intel build is untested. Pro is Apple Silicon only.

Problem	Next step
The old display sidebar or the separate Bookmarks / Aerials page is missing	Open Overview to choose a display. Use Wallpaper Library and its filters to browse content. Yellow bookmarks filter local library entries; pink Workshop likes save online items for later.
Controls cannot be clicked during a guide	Close the floating tour with its close button or `Esc`. Reopen it from Settings → About → Welcome Tour.
Closing the window did not stop the wallpaper	Closing the management window leaves the app running. Use the menu-bar global switch to hide wallpapers, or Quit to exit.
A saved change has not appeared on the desktop	Check the global switch, the display's pause reason and any load failure. A preview cover or saved value alone does not confirm that the wallpaper is rendering.

Problem	Check	Fix
Nothing renders, or the wallpaper is black	Is a source assigned in Overview → display → Wallpaper? Is the global switch on?	Assign a source. Turn the menu-bar master switch off and on.
Wallpaper keeps pausing	Pause rules: full-screen, 85% or more occlusion, battery, Low Power Mode, app exceptions	The menu bar and the display's detail header name the rule. For configurable rules, adjust Settings → Performance or add a never pause exception. Safety suspends cannot be overridden. See Pause rules.
Second display stays blank	Does the source's file permission cover that display's setup?	Reopen the display's detail panel and assign the source again.
Large video stutters	Source resolution and codec, overlays, resource pressure	Try a lower-resolution source. Adjust the frame-rate ceiling. Disable overlays to isolate the cause. Changing preload trades RAM for disk and decoder work.
Desktop clicks feel blocked (scenes)	Scene click interaction captures mouse clicks.	Disable click interaction for that display and reload.
Wallpaper vanished after an external drive was ejected	Is the video or web wallpaper stored on that drive?	The display keeps its configuration while the drive is away. Reconnect the drive; the display reloads on its own. Use Reload display if it does not.
Wallpaper stays paused after relaunch or replugging	Did you pause that display, or use the global toggle, earlier?	A manual pause persists. Press play, or pick a wallpaper for that display.

Problem	Check	Fix
Schedule does not switch	Overlapping slots? Is the wallpaper file still accessible? Was the app paused at that time?	Fix highlighted conflicts and save the slot again. Automation sleeps while the screen is locked or asleep and catches up once on wake. Missed slots do not fire afterwards.
Playlist interval is ignored	At least two valid entries? Is Playlist mode on?	Reset the interval and save again. Picking a wallpaper yourself, applying a scheme or applying a Workshop item restarts the countdown. While you are away the countdown freezes, then continues from what was left.
A wallpaper is marked Skipped	It failed to load twice. Skipped wallpapers in Wallpaper Automation shows the reason.	Fix the source, then click Enable Again.

Problem	Check	Fix
Web folder will not load	Can an index file be found in the folder?	Point at the `.html` file directly.
Scene import fails right away Pro	A project needs `project.json`. A library folder contains project subfolders.	Choose the project folder or a supported library folder, then read the reported failure. Windows executable wallpapers are not supported.

Problem	Check	Fix
Downloads fail	SteamCMD state, Steam sign-in	Open Settings → Workshop. The Steam connection section diagnoses the Steam library, SteamCMD and your account, and can auto-configure. Expand Diagnostics there for individual checks.
Set up SteamCMD (or Install SteamCMD in onboarding) fails	The failure message names the step: manifest, download, checksum or signature.	Retry. A mismatch can mean an incomplete download or a trust failure; it does not prove a specific cause. Do not bypass verification. Use a verified existing install if needed.
A SteamCMD you picked stops working	It is verified again on every run. An upgrade that changed its signature is rejected.	Pick it again with Choose SteamCMD, or switch to a managed install.
Browse shows nothing	Filters, connection, and API-key status for API-only features	Clear restrictive filters and retry. Public browsing can work without a key; creator, preset and API queries may need one. Presets are hidden from general browse by default.
Import says an item “is already in your library from another folder”	The library keeps one entry per Workshop item.	Use the entry already in the library. A Steam download of the same item asks before it replaces a local copy.
Preset list on a wallpaper is empty	Listing presets needs a Steam Web API key. Downloading them needs SteamCMD.	Add the key first. “No presets have been published for this wallpaper” means exactly that.

Problem	Check / next step
Apple Music progress or controls are unavailable	Allow Loomscreen to control Music in macOS Privacy & Security → Automation. A track without a usable playhead cannot show timed progress.
Lyrics are missing or static	Enable lyrics, then check your connection and track matching. Not every track has timed LRCLIB lyrics.
Weather widget shows no current conditions	Select a system or manual location, then check Weather settings and network access.
An imported backup contains a scene, but Lite shows no wallpaper	Lite keeps the configuration data but cannot run Pro scenes. Choose a supported video or web source, or open the setup in Pro.
System Wallpaper is unavailable	It requires macOS 26+ and a compatible provider. If its status says the provider is paused, use the normal video wallpaper. A newly added video still has to be selected in macOS Wallpaper settings.
Update banner remains after dismissing an update	The retained Sparkle session can keep the badge visible. Use the update dialog for its actions. This is not a second download.
Update download or verification fails	Retry on a working connection. Do not bypass signature verification. A matching DMG and checksum are available from Releases.

Toggle the relevant pause rules in Settings → Performance and test again.
Export your configuration from Settings → Backup & Restore before experimenting.
Use Settings → About → Report a Bug. It pre-fills diagnostics and recent log lines.
Add reproduction steps and file an issue on GitHub.