Menu ▾ ▴

Troubleshooting Common

Bayram Emekli

Troubleshooting — Common Problems

This page covers the problems people hit most often: a wallpaper that won't show, a black screen, audio that won't react, high CPU/GPU usage, an offline Store, and missing runtimes. Each section gives the likely cause and a concrete fix, with links to the deeper reference pages. For settings/startup/GPU-specific issues, see Troubleshooting-Settings-Startup-GPU.

📷 Screenshot needed: Portal → Settings → Wallpaper page showing the per-type engine selectors (used to switch engines while troubleshooting).

Contents

The wallpaper won't show

When you choose Use but nothing appears, the engine for that wallpaper type usually failed a runtime check or can't render the type.

Things to check, in order:

  1. Engine runtime requirement. Each engine has a prerequisite (WebView2 runtime for WebView, VC++ redist for CefSharp, Windows 10 1607 for MpvPlayer). See Runtime-Dependencies.
  2. Try a different engine for the type. Go to Settings → Wallpaper and pick another engine for that type. Defaults are MpvPlayer (Gif/Video), CefSharp (Url/Web/YouTube), Aurora (Application). The allowed engines per type are:
    | Type | Allowed engines |
    |------|-----------------|
    | Gif | Vexana, Xavier, WebView, CefSharp, MpvPlayer, VlcPlayer |
    | Url | WebView, CefSharp |
    | Web | WebView, CefSharp |
    | Video | Nebula, WebView, CefSharp, MpvPlayer, VlcPlayer |
    | YouTube | WebView, CefSharp |
    | Application | Aurora |
    See Choosing-Engines and Engines-Overview.
  3. Type/engine mismatch. If a type is assigned to an engine that can't render it, the engine's Configure() switch closes silently and nothing displays. Re-pick a compatible engine. See Engine-Comparison.
  4. Wallpaper version too new. If the wallpaper's AppVersion is newer than your installed app, the engine refuses to load it. Update Sucrose. See A library item is marked "Incompatible".
  5. Reload the engine. Switching wallpapers kills the old engine and launches the new one. Force a reload from the tray, or re-select the wallpaper. See Lifecycle.

If it still fails, collect logs (see the last section) and check the matching engine log under %AppData%\Sucrose\Log\ (e.g. MpvPlayerLive-yy.MM.dd.log, CefSharpLive-yy.MM.dd.log).

Black screen / blank desktop

A black or blank desktop after applying a wallpaper usually points at hardware acceleration or a runtime issue, not a missing file.

  • Toggle Hardware Acceleration. In Settings → Wallpaper, flip Hardware Acceleration (default true). With it off, WebView uses --disable-gpu/--disable-gpu-vsync, CefSharp uses disable-gpu, and MpvPlayer uses hwdec=no. Some GPUs/drivers render black with GPU compositing on. See Choosing-Engines.
  • Switch the engine. For video, try Nebula (OS codecs) instead of MpvPlayer, or vice-versa. For web/url, try WebView instead of CefSharp. See Engine-Comparison.
  • Check the GPU preference. Sucrose can set a per-app GPU preference in the Windows DirectX registry key; a bad value can pin rendering to the wrong adapter. See Troubleshooting-Settings-Startup-GPU.
  • Crash Mode. If Explorer/desktop attachment broke, the Crash Mode (CrashExplorer) option can restart Explorer on a crash. See Settings-Wallpaper.

Audio reactivity / system data isn't working

This is the single most common "it's broken" report, and it's almost always by design rather than a bug.

Audio-reactive and system-status data is only injected into:

  • the Web wallpaper type,
  • rendered by WebView or CefSharp (the browser engines).

Video, Gif, and Application engines never receive system data (Aurora apps get volume only; MpvPlayer/VlcPlayer/Nebula are pure media playback). See Create-Audio-API and Engine-Comparison.

Checklist:

  1. Is it a Web wallpaper on a browser engine? Confirm the type is Web and the Web engine is WebView or CefSharp (Settings → Wallpaper). See Type-Web.
  2. Does the wallpaper declare the hook? The wallpaper's SucroseCompatible.json must name the callback (e.g. SystemAudio). Only declared hooks are activated. See Create-JS-Bridge.
  3. Is the data service running? When a Web wallpaper requests audio, the engine turns on Backgroundog's AudioRequired and opens a communication channel. Make sure Performance Counter is on (it starts the Sucrose.Backgroundog service). See Backgroundog-Service.
  4. Is audio actually playing? The spectrum comes from WASAPI loopback (what you hear). If nothing is playing, obj.Data is all zeros (silence). The visualizer reacts to system output, not microphone input. See Create-Audio-API.
  5. Communication channel. The transport defaults to Transmission (CommunicationType); the alternatives are Pipe and Signal. If a firewall blocks the loopback TCP port, try Pipe or Signal. See IPC.

High CPU or GPU usage

Live wallpapers are real-time renderers, so some load is expected — but you can cap it.

  • Use the performance rules. Set Processor performance, Graphic performance, and Memory performance to Pause or Close, and set their thresholds (ProcessorUsage 70, GraphicUsage 70, MemoryUsage 80 by default). When usage crosses the threshold the wallpaper pauses/closes automatically. See Performance-Rules and Settings-Performance.
  • Pause for fullscreen apps. Set Full Screen to Pause/Close so games and full-screen video suspend the wallpaper. See Performance-Rules.
  • Use Heavy pause. Set Pause performance type to Heavy so paused engines have their threads suspended (including browser children and the Aurora app), not just rendering stopped. See Backgroundog-Service.
  • Pick a lighter engine. Pure-WPF GIF engines (Vexana/Xavier) and Nebula video are lighter than Chromium-based engines. See Engine-Comparison.
  • Turn on Hardware Acceleration. Offloading to the GPU often reduces CPU load (default is on). See Choosing-Engines.

The Store is offline or empty

The Store page has three states: Full (loaded), Unknown (server reachable but no data), and Broken (no network).

  • Broken (offline). The network host check failed. Confirm you have internet access, then reopen the Store. See Using-Store.
  • Unknown (no data). The server responded but returned nothing for the current backend. Try switching the Store Server between GitHub and Soferity (Settings → Personal); switching clears the Store cache (Store.json, Pattern.json). See Settings-Personal.
  • Stale catalog. Clear the Store cache from Settings → System → Store Temporary → Start (clears %AppData%\Sucrose\Cache\Store). See Cache-Management.
  • Adult items hidden. If a category looks empty, the Adult content filter may be hiding items. See Using-Store.

WebView2 is missing or out of date

The WebView engine needs the Microsoft Edge WebView2 runtime, version 131.0.2903.70 or newer. If it is missing or too old, the engine shows a dialog with Continue / Download / Remember / Close.

  • Choose Download to fetch and silently install the WebView2 bootstrapper automatically.
  • Choose Remember to snooze the prompt for one day.
  • Or install it manually from https://go.microsoft.com/fwlink/p/?LinkId=2124703.

After installing, re-apply the wallpaper. See Runtime-Dependencies and Engine-WebView.

VC++ redistributable is missing or out of date (CefSharp)

The CefSharp engine needs the Microsoft Visual C++ Redistributable, version 14.40.33816.0 or newer. If it is missing or too old, CefSharp shows a Continue / Download / Remember / Close dialog.

  • Choose Download to fetch VC_redist.<arch>.exe automatically.
  • Or install it manually from https://aka.ms/vc14/vc_redist.<arch>.exe.

If you can't fix the VC++ runtime right now, switch the Url/Web/YouTube engine to WebView as a workaround. See Runtime-Dependencies and Engine-CefSharp.

MpvPlayer won't start on older Windows

The MpvPlayer engine performs a pre-launch check (IsRedstone1) that requires Windows 10 Anniversary Update (version 1607 / Redstone 1) or newer. On older builds it shows a warning box and closes.

Fix: update Windows to 1607+, or change the Gif/Video engine to a non-mpv engine — Vexana/Xavier/WebView/CefSharp for GIF, Nebula/WebView/CefSharp for video. See Engine-MpvPlayer and Choosing-Engines.

The wallpaper flickers/restarts when I change a setting

This is expected behavior. Many settings apply live by killing and restarting the live engine (Kill.Stop() then Run.Start()), or by sending a command through Commandog. Changing the engine, display mode, stretch, or other engine-affecting settings will briefly restart the wallpaper. See Lifecycle and Multi-Monitor.

A library item is marked "Incompatible"

A wallpaper is "Incompatible" when its required AppVersion is newer than your installed Sucrose version; the Use action is disabled for it. Update Sucrose to a build at least as new as the wallpaper's AppVersion. See Updating-Sucrose, Managing-Library, and Create-Package-Format.

Also note: library entries without a valid SucroseInfo.json (missing Preview/Thumbnail/Source) are skipped, and if Delete corrupt (DeleteCorrupt) is on they are deleted on load. See Settings-Personal.

No window appears — only a tray icon

The tray icon is owned by the Launcher process, and the Portal window may be minimized to tray. Click the tray icon to open the Portal, or relaunch Sucrose (a second launch opens the Portal rather than starting a duplicate). If Notify Icon visibility is set to Hide, you won't see a tray icon at all — relaunch to open the Portal and re-enable it on the General settings page. See Theme-Tray-Startup, Portal-Interface-Tour, and Single-Instance-Mutexes.

How to collect logs for any of the above

Per-process logs live in %AppData%\Sucrose\Log\<Process>-yy.MM.dd.log (for example Portal-yy.MM.dd.log, CefSharpLive-yy.MM.dd.log). To bundle them for a bug report:

  1. Open Settings → System → Log Temporary → Create to produce a zip (named sucrose_log_yyyyMMdd_HHmmss.zip) of your Log and Setting folders (it excludes the sensitive Objectionable.json).
  2. Attach the zip to a GitHub issue.

See Logs-Diagnostics and Getting-Help.

See also

Related

Wiki: FAQ
Wiki: IPC
Wiki: Lifecycle

Auth0 Logo