OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
omarchy-theming high common DISPUTE

Recover the top bar after docking, a resolution change, or a lock that killed the shell

desktophyprlandlaptopomarchyomarchy-4wayland
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

Cause and diagnostics are solid. Issue #6684 is titled "omarchy-shell exits when locking with a screen that has no valid Wayland output — bar disappears and the session is left on 'lockscreen app died'" and quotes both log lines the record quotes, including the no-crash-report detail. #6501 is an open PR adding bar.screens, so "still an open feature request" is right. Bar.qml carries useTransparentForeground and debugBarGeometry(), hyprlock is genuinely absent from install/omarchy-base.packages (only hyprland, hyprland-guiutils, hyprland-preview-share-picker, hyprpicker, hyprsunset, xdg-desktop-portal-hyprland), and shell/plugins/lock/manifest.json declares id "omarchy.lock", so the killall -9 hyprlock remark is correct. omarchy-shell shell ping is real (omarchy-restart-shell polls exactly that), so the watchdog unit is sound, and it cannot fight a live lock because omarchy-restart-shell refuses while a locker reports secure. The defect: hyprctl --instance 0 eval 'hl.clear_crashed_lockscreen()' names a function that does not exist. It appears nowhere in the Omarchy tree, nowhere in the Hyprland Lua config docs, and searches turn up only the documented recovery (misc:allow_session_lock_restore plus relaunching a lock client). Omarchy already sets allow_session_lock_restore = true in default/hypr/looknfeel.lua and bin/omarchy-restart-shell implements the whole recovery itself: omarchy-hyprland-session-locked detects LOCK in solitaryBlockedBy, and when no live locker answers it restarts the shell and re-locks so you can authenticate out.

The cause above was not rewritten and may still contain the error described. The fix below is the corrected version.
RISK

hl.clear_crashed_lockscreen() unlocks the session **without a password**. Only run it at the physical machine, and lock again (omarchy system lock) immediately afterwards. The watchdog timer above deliberately does not clear a crashed lock, only restart the shell. Do not extend it to call clear_crashed_lockscreen, or an idle machine will unlock itself. omarchy restart shell refuses to run while the session is genuinely locked, which is intended.

Symptom

You dock the laptop or plug in a second monitor and the new display gets windows but no bar and no wallpaper. hyprctl monitors lists it fine, hyprctl layers shows nothing on it. Or after toggling bar transparency on and off, one monitor's bar text and icons stay washed out at about 70% opacity while the other monitor is correct. Or the machine idles, locks, and you come back to Hyprland's "it looks like you locked your screen but the lockscreen app died" wall, and after clearing it the bar is gone from every monitor, with DEBUG: Not creating lock surface for screen QScreen(0x…, name="") as it is not backed by a valid wayland output and WARN: The Wayland connection experienced a fatal error: Invalid argument as the last two lines the shell wrote.

Cause

On Omarchy 4 the bar is a Quickshell surface created per QScreen, not a per-monitor process. Screens are bound at shell start and on wl_output events, so an output that arrives late, is re-modeset by a dock, or briefly presents as a screen with an empty name (DPMS, lid close, monitor sleep) can end up with no bar surface. In the lock path that same empty-named screen is fatal: the shell correctly declines to create a lock surface for it and then the Wayland connection dies, taking omarchy-shell (and therefore every bar) with it, writing no crash report (issue #6684). Per-Bar state such as useTransparentForeground is also not re-derived after a transparency toggle, which strands one monitor's foreground at reduced opacity (issue #8024). There is no per-monitor bar restriction to configure around this: bar.screens is still an open feature request (issue #6501).

Fix

Drop the hl.clear_crashed_lockscreen() line, because there is no such function. From a TTY (Ctrl+Alt+F2) or over SSH as the session user, the shell restart IS the recovery:


omarchy-hyprland-session-locked; echo "locked=$?"   # 0 = compositor holds a session lock
omarchy restart shell                                # restarts and re-secures the lock so you can authenticate

It prints "Refusing to restart Omarchy shell while the session is locked." only when a live locker reports the lock secure. In the dead-locker case it proceeds, relocks, and exits 0 (or tells you the lock was not re-secured). If the compositor was started without it, make sure lock restore is permitted first (Omarchy sets this by default in default/hypr/looknfeel.lua):


hyprctl keyword misc:allow_session_lock_restore 1

Everything else in the record (the geometry/journal probes, hyprctl reload before the shell restart after a dock, and the watchdog timer) is correct as written.

Verify

hyprctl layers | grep -c omarchy-bar equals the number of enabled monitors, and omarchy-shell shell debugBarGeometry reports non-zero geometry with 'visible': True for each. Unplug and replug the external display. The bar comes back on it on its own.

Sources

bar-missing-or-wrong-after-monitor-hotplug