omarchy-desktop-rendering
暂无简介
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-24
- Stars
- ★ 0
- Forks
- 0
02 资源文件 1
- 参考文档skill.json509 B
03 SKILL.md 正文
omarchy-desktop-rendering
Omarchy Desktop Rendering Troubleshooting
Diagnosing why an Omarchy (Hyprland/Wayland) desktop renders wrong: shrunk into a small square, tiny floating windows, missing bar or background, Xwayland fallback, or incorrect scaling.
The omarchy skill covers config authoring. This skill covers why the
resulting desktop looks broken and how to close the loop on the symptom.
Core Principle: verify the symptom, not the config
A display bug can persist while every config file looks correct. monitors.lua
can be right, hyprctl configerrors can be clean, and the desktop can still
render wrong. Never report "root cause fixed" on config state alone.
When the user says a previous fix didn't work, treat the earlier diagnosis as suspect and re-derive from the live symptom.
Diagnostic Order
Run these in order — each rules out a layer before you touch config.
1. Is the panel itself correct?
export HYPRLAND_INSTANCE_SIGNATURE=<sig> # from ls /run/user/$(id -u)/hypr/
export XDG_RUNTIME_DIR=/run/user/$(id -u)
hyprctl monitors -j
Native resolution, expected scale, transform: 0. If this is wrong it IS a
monitor-config bug. If it is correct, keep going — the bug is elsewhere.
2. Did the shell's layer surfaces attach?
hyprctl layers # raw output, NOT -j
Look for namespace: omarchy-bar and namespace: omarchy-background.
Missing = the Omarchy shell (quickshell) failed to attach as a layer client.
3. Are there degenerate fallback windows?
hyprctl clients -j
Tiny floating windows (e.g. 80x80, 1x24) with empty class and
title: "quickshell" are shell surfaces that fell back to Xwayland.
4. What does the shell's own log say?
journalctl --user --since today _PID=$(pgrep -f 'quickshell -n -p') \
| grep -iE 'WlrLayershell|QT_QPA_PLATFORM|WAYLAND_DISPLAY'
Authoritative error strings:
Could not create attached properties object 'qs::wayland::layershell::WlrLayershell'→ layer-shell attach failing; Qt is running on X11.WAYLAND_DISPLAY is present but QT_QPA_PLATFORM is "xcb"→ same root cause, stated outright by quickshell.
5. Is there stacked scaling?
gsettings get org.gnome.desktop.interface text-scaling-factor
Must be 1.0 when Hyprland uses a fractional output scale (e.g. 1.25).
A value >1 multiplies on top of the compositor scale and shrinks Xwayland
clients into a small central region.
Root Cause: forced X11 Qt platform
Never force QT_QPA_PLATFORM=xcb in ~/.config/hypr/hyprland.lua.
Omarchy's default is wayland;xcb ($OMARCHY_PATH/default/hypr/envs.lua).
Forcing xcb makes quickshell an Xwayland client, so every layer surface —
bar, background, notifications, OSD, menu, keyboard panel — fails to attach and
falls back to tiny floating X windows centered on screen. The user sees exactly
"the desktop shrunk into a small square."
If one Qt app genuinely needs xcb (SteamVR's bundled Qt5 only ships the xcb
plugin), override it per-app in autostart.lua, never session-wide.
Full Fix Sequence
All steps are required; skipping the env step is the usual reason a "fix" appears not to take.
- Remove the
QT_QPA_PLATFORMoverride from~/.config/hypr/hyprland.lua. -
hyprctl reload && hyprctl configerrors # must be clean gsettings set org.gnome.desktop.interface text-scaling-factor 1.0 hyprctl reloaddoes not update the systemd user session env. The stale value persists and every newly spawned shell inherits it:systemctl --user set-environment QT_QPA_PLATFORM=wayland omarchy restart shell- Verify live, all three must pass:
hyprctl layersshowsomarchy-bar+omarchy-backgroundhyprctl clients -jshows no tiny quickshell windows- shell journal log has zero
WlrLayershellerrors
Pitfalls
- Parsing
hyprctl layers -j: the JSON nests surfaces underlevels -> <n> -> [ ... ]; naive parsers report "no layers" when the bar is in fact attached. Read the rawhyprctl layerstext output to be sure. - Session env vs config env:
hl.env()only affects processes spawned after it takes effect, andhyprctl reloaddoes not refresh the systemd user environment. Usesystemctl --user set-environment. - Backup files are evidence: dated
monitors.lua.bak.*files reveal what the config looked like shortly before a broken login. Compare them before assuming the current file is innocent. - A stale external-monitor rule (e.g.
HDMI-A-2at1366x0) can survive in a backup while the current file is clean — confirm which one is loaded. - Post-login persistence: removing the
hl.envline stops Hyprland from setting the variable, but if another source (uwsm,environment.d) exports it, the symptom returns on a fresh login. Verify after a real logout.
Verification Discipline
A display fix is complete only when the exact symptom the user reported is confirmed gone in the live session. Config correctness is necessary but not sufficient. When a user reports "still the same after you said it was fixed", re-open the whole diagnosis rather than re-asserting the previous conclusion.
References
references/rendering-case-log.md- worked case: shrunk-desktop root cause, exact commands, and verified output.