Troubleshooting

Most WebDecks display problems come down to how your browser hands frames to your GPU. Here are the ones we know about and how to work around them.

Blank, white, or black screen on Linux (Wayland)

On a Linux desktop running Wayland (GNOME, KDE Plasma, Hyprland, Sway and others), current Chrome and other Chromium-based browsers cannot display WebGPU on screen. WebDecks draws its entire interface with WebGPU, so the page loads but the canvas stays white or black.

This is a browser and driver limitation, not a WebDecks bug. Chrome's native-Wayland mode is incompatible with the Vulkan backend that WebGPU relies on — the frames are rendered but never presented. NVIDIA GPUs are affected the most.

The fix: run Chrome under XWayland

Launch Chrome with the X11 backend, which presents WebGPU correctly. From a terminal:

google-chrome-stable --ozone-platform=x11 --ignore-gpu-blocklist --enable-features=Vulkan

If Chrome is already running, that command just opens a tab in the existing (still-broken) window — quit Chrome completely first, or launch a separate instance by adding --user-data-dir=/tmp/webdecks.

Make the fix permanent

Copy the desktop launcher into your user directory and add the flags to every Exec= line, so launching Chrome from your menu always uses XWayland:

cp /usr/share/applications/google-chrome.desktop ~/.local/share/applications/
# then add to each Exec= line:
#   --ozone-platform=x11 --ignore-gpu-blocklist --enable-features=Vulkan

This switches all of Chrome to XWayland. To undo it, delete ~/.local/share/applications/google-chrome.desktop.

The interface looks too small (HiDPI)

XWayland does not pick up fractional display scaling, so on a HiDPI screen the interface can render small. Add a scale factor that matches your display (for example 1.5) to the launch flags:

--force-device-scale-factor=1.5

"Software (CPU) graphics fallback" warning

If WebDecks shows a banner saying it is running on a software (CPU) fallback, your browser could not reach a hardware GPU adapter. The same flags above — --ignore-gpu-blocklist --enable-features=Vulkan — let Chrome use the real GPU instead of the slow software renderer.

Why this happens, and when it will be fixed

Chromium is actively working on native-Wayland WebGPU through its new Skia Graphite and Dawn rendering path. Until that ships and is enabled for Linux, running under XWayland is the reliable workaround. You can follow the upstream reports:

Something else broken?

If your problem isn't here, we'd love a clear report so we can fix it.

Report a bug