OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
wayland-compat medium common DISPUTE

Fix Qt apps that refuse to start or silently fall back to XWayland

omarchyarchendeavouroscachyosmanjarohyprlandwaylandxwayland
AUDITED Audited against its sources and confirmed accurate. · checked against Omarchy omarchy 4.0.4-1 on 2026-10-05
AUDIT NOTE

Checked on this workstation (omarchy 4.0.4-1): /usr/share/omarchy/default/hypr/envs.lua sets hl.env("QT_QPA_PLATFORM", "wayland;xcb") and xwayland.force_zero_scaling = true, and the quattro copy of envs.lua has the same line. pacman -Q shows qt6-wayland 6.11.2-1 installed and qt5-wayland absent (qt5-base is also absent here, so a stock install has few or no system Qt5 apps, but the claim is conditional and holds). qt5-wayland exists in extra (5.15.19+kde+r55 per the archlinux.org JSON). The cited BBS thread 284214 has the exact error text, names TeamViewer, DaVinci Resolve and Shotcut, and the answer that proprietary apps bundle their own Qt without the Wayland plugin. The Hyprland wiki environment-variables page lists hl.env("QT_QPA_PLATFORM", "wayland;xcb") as the recommended fallback, matching the Lua fix. hyprctl clients on 0.56.2 prints xwayland: 0/1 exactly as the verify step expects. Not exercised: launching an actual bundled-Qt app.

Symptom

A Qt program (TeamViewer, DaVinci Resolve, Shotcut, an AppImage) will not start:


qt.qpa.plugin: Could not find the Qt platform plugin "wayland" in ""
Available platform plugins are: xcb.
This application failed to start because no Qt platform plugin could be initialized.

Or, on Omarchy, the app starts but looks tiny or blurry next to everything else and hyprctl clients shows xwayland: 1 for it.

Cause

Qt picks its windowing plugin from QT_QPA_PLATFORM. With the value wayland alone, any Qt build without the Wayland plugin has nothing to fall back to and exits. Proprietary apps and AppImages bundle their own Qt, often without that plugin, so system packages cannot fix them. System Qt5 apps need qt5-wayland for native Wayland (Qt6's plugin is in qt6-wayland). Omarchy 4 sets QT_QPA_PLATFORM to wayland;xcb in /usr/share/omarchy/default/hypr/envs.lua, so the hard failure does not happen on stock Omarchy, but qt5-wayland is not installed, so every system Qt5 app silently runs on XWayland, where force_zero_scaling leaves it unscaled.

Fix

**Plain Arch, if you exported QT_QPA_PLATFORM=wayland:** give it a fallback wherever you set it.


-- Hyprland 0.55+ (~/.config/hypr/hyprland.lua)
hl.env("QT_QPA_PLATFORM", "wayland;xcb")

# Hyprland 0.54 and older (hyprland.conf)
env = QT_QPA_PLATFORM,wayland;xcb

**One app with a bundled Qt:** run it on XWayland explicitly.


QT_QPA_PLATFORM=xcb /path/to/app

To make that stick, copy its .desktop file into ~/.local/share/applications/ and prefix the Exec= command with env QT_QPA_PLATFORM=xcb .

**System Qt5 apps (Omarchy and Arch):** install the plugin so they run natively.


sudo pacman -S --needed qt5-wayland

Restart the app afterwards. Bundled-Qt apps do not benefit from this.

Verify

The app starts. hyprctl clients | grep -B2 -A12 -i <app> shows xwayland: 0 for system Qt5 apps after installing qt5-wayland, or xwayland: 1 where you forced xcb on purpose.

Sources

qt-app-no-qt-platform-plugin-wayland