Troubleshooting

Troubleshooting

Fixes for the most common problems, how safe restart works, how to read OWE's logs, and how to report a bug.

A scene says it needs assets, or looks empty

Scenes need Wallpaper Engine's assets from your Steam copy.

1. Open Settings › Assets (or Set Up Assets… in the menu bar menu).
2. Check Status. If it says Missing, click Install from Steam (log in on the Workshop tab first) or Choose Folder….
3. After moving your storage folder, install the assets again if needed.

See Wallpaper Engine assets.

A wallpaper won't play

Symptom	Likely cause	What to try
Application wallpaper does nothing	application wallpapers are Windows programs	Not supported
A Workshop scene renders partly	Missing Workshop dependencies	Details › Download All
A scene draws wrong or not at all	An unsupported feature, a shader that failed to translate	Check the logs (below) and report it
A web wallpaper is blank or grey	The page needs online content, or its own scripts fail	Check your connection; see the logs in the Web category
The wallpaper was skipped at launch	Safe restart (below)	Retry from the notice or apply it again

Black screen or no wallpaper

• Open Displays and check the display is Enabled and has a wallpaper.
• Check the playback rules: Stop (free memory) hides a display's wallpaper while the rule applies (e.g. on battery or a fullscreen app).
• Check that Pause or Stop Wallpapers in the menu bar menu isn't on.
• After an unclean exit, the previous wallpapers are not restored automatically (see safe restart).
• A scene without assets shows that it needs them.

Audio-reactive wallpapers don't move

• Grant System Audio Recording (Screen & System Audio Recording before macOS 14.2) in Settings › Permissions, then click Recheck. No restart is needed.
• Without the permission, wallpapers receive silence.
• Something must actually be playing on the Mac.

Now Playing shows nothing

• Turn on Media integration support in Settings › Optimizations.
• The live session needs macOS 15.4 or later.

Performance

Symptom	Try
Fans, heat, battery drain	Lower FPS; keep Render Resolution at Display or turn on MetalFX Upscaling; move Quality ↔ Efficiency toward Efficiency; add battery/fullscreen playback rules
One scene is slow	Keep Scene Detail at Match Display; set Texture Resolution to High Performance; lower Volumetrics, Post-Processing or the Particle Budget
The first load of a scene is slow	Shaders are translated the first time a scene uses them, then cached. Later loads are fast.
Several displays	One wallpaper on several displays with the same properties renders once; different properties run separately

See Settings › Performance.

Safe restart

OWE protects you from a wallpaper that crashes, hangs or bogs down the Mac:

• While wallpapers are showing, OWE keeps a note of them, cleared on a clean quit. If the app didn't quit cleanly, those wallpapers are not restored at the next launch, the playlist stays paused, and a notice at the top right offers Retry or Dismiss.
• A wallpaper behind two unclean exits in a row is flagged: its tile shows a warning triangle, applying it asks first, and playlists skip it.
• A watchdog unloads the showing wallpapers when the app stays badly degraded (the main thread stalls, or frame times stay very slow), before you would have to force-quit.
• A shader whose translation hung or crashed the app is skipped on later launches, while every other shader still translates.

SteamCMD problems

Problem	Try
"steamcmd Not Found"	Wait for the automatic install; click Install SteamCMD in Settings › Assets or the Workshop tab; or brew install steamcmd, then Re-detect
The install fails	Check your connection and free disk space, then Try Again
Login fails or loops on Steam Guard	Use Log in with SteamCMD in Terminal, then I've Signed In
"SteamCMD has no saved login for this account"	Finish signing in in Terminal first
Downloads fail "isn't connected"	Connect the storage drive, or choose another storage folder
Workshop won't browse	Add a Steam Web API key

More in SteamCMD and Steam login.

Reading the logs

OWE writes to the macOS unified log under the subsystem app.openwallpaperengine. Categories include SceneVM, SceneScript, AudioCapture, ShaderTranslator, Import, Workshop, TEXParser, Perf, App, Library, Web, Settings and UI.

1. For more detail, set Settings › Diagnostics › Developer › Log Level to Verbose (errors are always logged).
2. In Terminal, stream the log. Use the full path /usr/bin/log, because some shells define their own log command:

/usr/bin/log stream --predicate 'subsystem == "app.openwallpaperengine"' --level debug

3. Or look back over the last ten minutes:

/usr/bin/log show --last 10m --predicate 'subsystem == "app.openwallpaperengine"' --info --debug

Add AND category == "ShaderTranslator" (or another category) to narrow it.

Tip

When a shader fails to translate, OWE writes the source the compiler rejected to /tmp/owe-failed-shaders, one file per shader and stage. Attach those files to a bug report.

Reporting a bug

Open an issue at https://github.com/deepratna-awale/open-wallpaper-engine-mac/issues with:

• your macOS version and Mac model;
• the OWE version (Settings › About);
• the wallpaper's Workshop ID or a link (don't attach Wallpaper Engine's own files);
• what you expected and what happened, with a screenshot if possible;
• the relevant log lines and, for shader problems, the files from /tmp/owe-failed-shaders;
• the values from Settings › Diagnostics.

Read more (for developers): Testing and WE-fidelity principles