Troubleshooting

Troubleshooting

Symptom → fix recipes. For broader background see Known Issues.

"Wallpaper Engine" doesn't appear in the wallpaper type dropdown

• The install didn't land in a path Plasma scans, or plasmashell wasn't restarted. Run:

  systemctl --user restart plasma-plasmashell.service

• Check that the QML plugin is on disk:

  ls /usr/share/plasma/wallpapers/com.github.catsout.wallpaperEngineKde/ \
     ~/.local/share/plasma/wallpapers/com.github.catsout.wallpaperEngineKde/ 2>/dev/null

  At least one of those should exist.

Wallpaper list is empty after setting the Steam path

• You probably picked steamapps/ or workshop/. Go up one level — the path should contain a steamapps/ folder, not be it.
• Confirm you've actually subscribed to at least one Wallpaper Engine wallpaper from inside Steam.
• Try:

  ls ~/.local/share/Steam/steamapps/workshop/content/431960/

  If empty, Steam hasn't downloaded any Workshop content for Wallpaper Engine yet.

Black or frozen desktop after applying

Likely a Vulkan or driver issue.

• Run vulkaninfo to verify Vulkan is alive.
• AMD: switch to RADV (default on Mesa) rather than AMDVLK.
• NVIDIA: make sure the proprietary driver matches your kernel; nvidia-smi should succeed.
• Try a Video wallpaper instead of Scene — if Video works but Scene doesn't, the problem is in your Vulkan stack.

Video plays without sound

• Check the plugin's audio mute toggle.
• For QtMultimedia, install GStreamer codec packages (gst-libav, gst-plugins-good, gst-plugins-bad, gst-plugins-ugly).
• Try switching to the MPV backend — see Video Backends.

High CPU / GPU usage

See Performance Tuning. Cap FPS at 30 first.

Theme switching makes the plugin's UI invisible

This project specifically fixes that bug — confirm you're on CaptSilver/... and not the original catsout/.... If you installed both at different times, uninstall the old one (see Uninstalling) and reinstall this one.

Collecting logs

When opening an issue, logs from plasmashell help a lot:

journalctl --user -u plasma-plasmashell.service -b | tail -n 200

Run it after reproducing the bug. For Scene-renderer-specific issues, the renderer's debug build can be run standalone — see wallpaper-scene-renderer/standalone_view.