troubleshooting

Troubleshooting

Common failure modes and how to diagnose them.

How to get useful diagnostic output

The default SignalRGBBridge.exe build is --noconsole — no stdout visible. When something's misbehaving, run the bridge with stdout visible instead:

Option A — run the Python source directly:

python wallpaper_bridge\bridge.py

You'll see UDP packet counts, WS client connects, settings pushes, etc. Plus any Python exceptions.

Option B — run the .exe from cmd so its stdout/stderr inherit the terminal (only works partially since --noconsole strips the handle — prefer Option A for debugging).

For SignalRGB-side plugin issues, the plugin writes its service.log / device.log calls to SignalRGB's plugin log file: %LOCALAPPDATA%\WhirlwindFX\SignalRgb\Logs\SignalRGB_*.log

Plugin not appearing

After copying SignalRGB_Desktop_Wallpaper.js and .qml to your Plugins folder, SignalRGB should hot-load within seconds.

If the device doesn't show up:

1. Confirm the Plugins folder path. With OneDrive Documents redirection, it's %USERPROFILE%\OneDrive\Documents\WhirlwindFX\Plugins\ (or OneDrive\Dokumente\… on German Windows). Without redirection, it's %USERPROFILE%\Documents\WhirlwindFX\Plugins\. SignalRGB only watches the redirected path.
2. Restart SignalRGB. Right-click SignalRGB's tray icon → Quit, then relaunch. Hot-reload sometimes doesn't trigger DiscoveryService.Initialize reliably; a full restart always does.
3. Check the SignalRGB log (SignalRGB_*.log, see above) — search for Custom Plugin File Loaded to confirm SignalRGB saw your file. If you see Error: Could not open module… that's a plugin runtime issue — please file an issue with the exact error.

Bridge won't start

Symptom: you double-click SignalRGBBridge.exe, no tray icon, nothing.

1. Open Task Manager → Details and search for SignalRGBBridge.exe. If it's not there, the exe failed to start (likely an antivirus quarantine on the PyInstaller bundle — temporarily disable AV / add an exclusion and retry, or build from source).

2. Port 17320 already in use — another bridge is already running (or a different program is using 17320). Check:

   Get-NetUDPEndpoint -LocalPort 17320 -ErrorAction SilentlyContinue
   Get-NetTCPConnection -LocalPort 17320 -State Listen -ErrorAction SilentlyContinue

   If something else is bound, kill it (or change bridgePort in the plugin's settings — but you'd then also need to rebuild the zips with a matching port hardcoded… not great, prefer killing whatever's conflicting).

Wallpaper stays black / "connecting…" status

The Lively wallpaper opens but never receives frames.

1. Enable the debug overlay for that screen: tray icon → Configurator… → pick the screen tab → Background → tick Show debug overlay (top-left status line on the wallpaper). The wallpaper now shows a tiny status line top-left.
2. Read the status:
   • connecting ws://127.0.0.1:17320/?screen=N… — bridge not running or wrong port. Confirm SignalRGBBridge.exe is in your tray.
   • disconnected — retrying… — bridge crashed or was killed. Start it again.
   • screen N live WxH @ X fps — wallpaper is connected and getting frames. If you still see no glow, the issue is on the SignalRGB side: confirm the device is on the canvas and a colourful effect is active.
3. Confirm the plugin is sending UDP. In SignalRGB's log (SignalRGB_*.log) search for [DesktopWallpaper] screen N frame #. If you see these, the plugin is firing; if not, the device isn't being rendered by SignalRGB (not on canvas / not active).

Wrong colours on wrong monitor

You set up two monitors, but the colours from Screen 1 are showing on monitor 2 (or similar).

The mapping happens in Lively, not in our code. Each wallpaper zip hardcodes a screen index in its HTML's <meta> tag:

Zip	Subscribes to
SignalRGB_Glow_Screen1.zip	UDP frames tagged screen=0
SignalRGB_Glow_Screen2.zip	UDP frames tagged screen=1
SignalRGB_Glow_Screen3.zip	UDP frames tagged screen=2

And the SignalRGB devices match:

• "Desktop Wallpaper - Screen 1" device sends UDP with screen=0 byte
• "Desktop Wallpaper - Screen 2" device sends with screen=1
• "Desktop Wallpaper - Screen 3" device sends with screen=2

So the chain is: SignalRGB device "Screen 1" → UDP screen=0 → bridge routes to WS clients with ?screen=0 → wallpaper from Screen1.zip.

To fix wrong-monitor mapping, just swap which monitor each Lively wallpaper is activated on. Or rearrange the SignalRGB canvas placements.

Debug overlay keeps showing despite being disabled

Should be fixed in v0.2.0. If you see it pop up anyway after upgrading, do a hard refresh:

• In Lively, deactivate the wallpaper, then reactivate. That re-loads the HTML page with the current code.
• If still leaking, please file an issue.

Tray Quit doesn't kill the bridge

Should be fixed in v0.2.0. If clicking Quit leaves SignalRGBBridge.exe in Task Manager, kill it manually from Task Manager → End task. Then file an issue with your Windows build (winver).

Background image won't load

Symptom: the wallpaper renders the glow correctly but no background image appears (or it's broken).

1. Path issue — confirm the file at the path you picked still exists. Browse to it from File Explorer.
2. Unsupported extension — the bridge's image proxy whitelists .png .jpg .jpeg .gif .webp .svg .bmp .ico. Other formats are rejected.
3. Bridge offline — without the bridge, the wallpaper can't fetch absolute-path images via the /image proxy.
4. Open the wallpaper's dev tools by running Lively in debug mode and inspect network requests. Or check the bridge's stdout (run from Python source) for [http] served … and any 404 not found lines.

SignalRGB shows too many / too few devices

Set Number of screens in the Configurator (top-right of the tab bar — Screens: 1 / 2 / 3 / 4). Plugin polls the bridge every ~2 seconds and adjusts. If it doesn't:

• Make sure the bridge is actually running (tray icon visible).
• Open http://127.0.0.1:17320/config in a browser — should return {"screenCount": N}. If the page errors, the bridge isn't running or the endpoint is broken.
• Restart SignalRGB if the plugin seems stuck.

Lively "Pause wallpapers" doesn't stop the glow

The wallpaper page implements Lively's window.livelyWallpaperPlaybackChanged(state) hook per the wiki spec and shows a red "⏸ PAUSED" badge in the top-right corner when the hook fires. It also subscribes to document.visibilitychange as a defensive fallback for hosts that suspend the surface without firing the Lively event. We deliberately do not pass --pause-event true in LivelyInfo.Arguments — newer Lively builds reject that as an unknown option (Wallpaper plugin exception on import). The pause hook still fires on builds that push it without the opt-in.

But whether either hook actually fires depends on the Lively build and the user's environment — some setups don't deliver the suspend IPC to the WebView2 player at all, in which case the visibilitychange fallback is the only signal the page gets.

Quick check: when you click "Pause wallpapers" in Lively's tray, do other Web-type wallpapers in your library actually pause (freeze)?

• No → Lively itself isn't pausing in your environment. This is a Lively-side issue; we can't work around it from a wallpaper page. File an issue at the Lively repo with your Lively version and Windows build.
• Yes for others but not ours → file an issue against this project with your Lively version (Settings → About in Lively).

Updated wallpaper but Lively still shows the old version

Symptom: you rebuilt + reimported a wallpaper zip (or pulled a new release), but the wallpaper in Lively keeps rendering the old behaviour — old layout, no parallax, missing widgets.

Lively extracts each imported wallpaper zip once into a random-hash folder under %USERPROFILE%\AppData\Local\Lively Wallpaper\Library\wallpapers\<hash>\ (MSIX build path differs; both end in Library\wallpapers\<hash>\). Re-zipping the source folder does not propagate — Lively never re-reads the original zip.

To pick up new HTML / JS / LivelyInfo.json changes:

1. In Lively's Library, right-click the wallpaper → Delete.
2. Drag the new zip onto Lively (or re-run the installer with Auto-import into Lively enabled — v0.7.0+ uses deterministic folder names signalrgb-glow-screen-{1,2,3}\, which the installer overwrites in place, so no manual delete needed for future updates).
3. Right-click each new tile → Set as wallpaper for the matching monitor.

The deterministic-folder auto-import is the v0.7.0 fix specifically for this footgun. Pre-v0.7.0 users coming from a manual drag-import still hit it once on the upgrade — after the installer takes over, subsequent updates are silent.

Lively import fails: "Unknown options are passed. WallpaperPluginException"

If Lively shows Error initializing — Unknown options are passed. Exception: WallpaperPluginException when importing the wallpaper, you're on the broken v0.7.0 Lively bundles — LivelyInfo.Arguments carried an invalid --system-cursor true value that Lively rejects on import. Fixed in v0.7.1 (Arguments reverted to null).

To recover:

1. Install v0.7.1 or newer (re-run the installer with Auto-import into Lively enabled, or grab the fresh SignalRGB_Glow_ScreenN.zip from the release page).
2. In Lively's Library, delete the broken tiles (the import error leaves a stub entry), then re-import the fresh zip.

The parallax + cursor-driven Pixelfx effects still work on v0.7.1 — they receive the cursor through the DOM mousemove listener whenever Lively's Wallpaper interaction setting is on, instead of through the rejected argument.

Parallax / cursor effects don't react in Lively

The 3D parallax (Configurator → Effects → 3D parallax) and the mouse-driven Pixelfx modes (Trail, Glow, Ripple — all) need real-time cursor coordinates. v0.7.1 reads them from the wallpaper page's DOM mousemove events, which only fire when the wallpaper surface is reachable by real mouse events:

• Lively — toggle the wallpaper's Wallpaper interaction setting to on (right-click the active tile → Customise → top of the panel). Click-through mode delivers no DOM mousemove events to the page, so the parallax / Pixelfx stays still.
• Wallpaper Engine — set Mouse input to Allow. Same logic.
• Builder / Configurator preview / browser tab — works automatically; those surfaces are normal interactive web pages.

Click-driven Pixelfx (the Ripple mode) additionally needs real clicks to reach the wallpaper, which is the same requirement as interaction-on.

Setting the SignalRGB plugin's Glow Grid Base Size > 36 errors out

Symptom: in SignalRGB's plugin settings, you bump Glow Grid Base Size to 64, 96, or 128, hit Save, and SignalRGB's log shows:

udp.error - Buffer too large. Max size is 4096 bytes!

This is the SignalRGB plugin sandbox's hard 4 KB udp.send() cap. The plugin and bridge do support larger grids — v0.6.0+ chunks frames > 4 KB across multiple datagrams (SC wire format) and the bridge reassembles them.

If you're seeing the error:

• Check the bundle versions match. Both SignalRGBBridge.exe and SignalRGB_Desktop_Wallpaper.js must be ≥ v0.6.0 — the chunked protocol is implemented in both halves. Old plugin file + new bridge (or vice versa) fall back to the single-packet SR format and hit the limit.
• Re-run the installer with Install the SignalRGB Desktop Wallpaper plugin enabled to drop the matching JS / QML in Documents\WhirlwindFX\Plugins\.
• Then re-pick 64 / 96 / 128 in the plugin settings.

Plugin's Aspect Ratio = Auto, but the glow grid is still square

The plugin's Auto mode reads the per-screen viewport from the bridge's GET /config endpoint, and the bridge only knows the viewport once a wallpaper page has connected via WebSocket and pushed its {type:"viewport", w, h} frame. Before that's happened, Auto falls back to 16:9.

Steps to check:

1. Is the wallpaper actually running? Set the wallpaper in Lively / Wallpaper Engine for that screen index. The viewport is sent on WS open + on window.resize (debounced).
2. Does the bridge see it? Open http://127.0.0.1:17320/config in a browser — the screens[] array should show {viewportW: …, viewportH: …} populated for each connected screen.
3. Is the plugin reading it? Check SignalRGB's log (SignalRGB_*.log); on every Update tick the plugin XHRs /config and updates its internal viewport cache. A grid change is logged as screen N grid CxR (aspect=Auto) — confirm the numbers match the monitor.

If the wallpaper has been running but the viewport is still 0, the WS connect happened before this beta. Reload the wallpaper (Lively: right-click → Unset + Set as wallpaper again; WE: similar) to re-trigger the viewport push.

If you'd rather not rely on Auto, pick a fixed aspect (16:9 / 21:9 / 32:9 / 9:16) or Custom + type the cols × rows.

Windows Defender flags SignalRGBBridge.exe as Trojan:Win32/Wacatac.C!ml

This is a false positive on the PyInstaller --onedir build. Wacatac.C!ml is a machine-learning heuristic detection — it fires on lots of PyInstaller-packed Python applications because the bootloader pattern (small native EXE that unpacks a Python interpreter + bytecode into _internal/ at startup) overlaps with common malware packers.

The bridge does nothing malicious. Source is at github.com/Delido/signalrgb-wallpaper and the build is reproducible (pwsh installer\build.ps1).

Recovery

1. Open Windows Security → Virus & threat protection → Protection history → click the Wacatac entry → Actions → Allow.
2. If the file was quarantined: click Actions → Restore. If Restore is greyed out, re-run the installer — it'll drop a fresh copy at the original path.
3. (Optional, only if it keeps re-flagging) Windows Security → Virus & threat protection → Manage settings → Exclusions → Add an exclusion → Folder, pick C:\Program Files\SignalRGBWallpaper (the v2.2.1+ install location; older versions lived under %LOCALAPPDATA%\Programs\SignalRGBWallpaper).

Help reduce false positives for everyone

The Microsoft Defender team accepts false-positive reports at microsoft.com/wdsi/filesubmission. A submission with the installer or SignalRGBBridge.exe typically clears the specific build's hash within 24-72 hours and trains the ML model away from this signature for future builds. Free, takes ~2 minutes, requires a free Microsoft account.

"Address already in use" on bridge startup

Port 17320 is occupied by an old bridge process that didn't exit cleanly. Either:

Get-Process -Name SignalRGBBridge -ErrorAction SilentlyContinue | Stop-Process -Force

Or Task Manager → End all SignalRGBBridge.exe entries. Then start fresh.

Still stuck?

File an issue at github.com/Delido/signalrgb-wallpaper/issues with:

• Windows version (winver)
• SignalRGB version
• Lively version (and whether it's Store or GitHub build)
• What you did, what you expected, what happened
• Bridge stdout output (run python wallpaper_bridge\bridge.py)
• SignalRGB log snippet if relevant (lines mentioning DesktopWallpaper)