OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
display-monitors low very-common DISPUTE

Newly plugged-in monitor has a black background and no bar until you restart the wallpaper/bar daemon

hyprlandwaylandomarchyomarchy-4omarchy-3archendeavouroscachyosmanjarolaptopdesktopdock
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

The hyprpaper half is accurate: the wiki documents monitor "If empty, will use this wallpaper as a fallback", the fit_mode values, hyprctl hyprpaper wallpaper '[mon], [path], [fit_mode]', listactive with output matching the record's sample, and the exact sentence "The fallback wallpaper only applies to monitors that have never had a specific monitor target assigned." hyprpaper #154's title is literally the quoted warning. The socat/IPC listener and o.launch_on_start are correct, and omarchy-restart-shell exists and behaves as described (kills every quickshell instance for the config dir, then relaunches via hyprctl dispatch 'hl.dsp.exec_cmd("omarchy-launch-shell")' so it inherits the session environment). Two problems. (1) The record is tagged omarchy-4 and leads with editing ~/.config/hypr/hyprpaper.conf, but Omarchy 4 does not ship or use hyprpaper at all. There is not one reference to it anywhere in the quattro tree, the background/bar/lock surfaces are all the Quickshell Omarchy shell, and omarchy-upgrade-to-quattro removes hypridle-era packages. An Omarchy 4 user will edit a file nothing reads and conclude the record is broken. (2) The closing claim that an Invalid config line at line N parse failure is documented in hyprpaper #154 is not supported. That issue is a user on pre-1.0 wallpaper = mon,path syntax, closed not_planned with "update hyprlang and hyprpaper", and never mentions a parse-failure line.

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

Symptom

I dock the laptop or plug in a second screen. Hyprland picks it up fine (windows move there, hyprctl monitors lists it), but the new display is just black behind the windows, and the top bar only draws on the original screen. hyprpaper's log says Monitor DP-3 does not have a target! A wallpaper will not be created. Killing and restarting hyprpaper and the bar fixes it until the next hotplug.

Cause

Wallpaper and bar daemons are ordinary Wayland clients, not part of the compositor. hyprpaper assigns a wallpaper per output at config-parse time. An output that did not exist then has no target, and hyprpaper logs exactly that message rather than falling back (hyprwm/hyprpaper #154, #110). The wiki is explicit that the empty-monitor entry is a *fallback* and "only applies to monitors that have never had a specific monitor target assigned", so if you have only named entries, a new connector gets nothing. Status bars behave the same way: many only enumerate outputs at startup, so a display that appears later gets no layer surface until the bar is restarted.

Fix

Split the record by platform up front, because the two cases share a symptom and nothing else.

**On Omarchy 4 (Quattro), hyprpaper is not installed and hyprpaper.conf is not read.** The wallpaper, bar and lock surface are all the Quickshell-based Omarchy shell. A display that appears after the shell started and gets no background or bar is fixed with one command:


omarchy-restart-shell

It kills every running instance for the shell config dir and relaunches it from inside the Hyprland session so it inherits the correct environment. It refuses to run while the session is genuinely locked, which is the intended guard. Confirm the outputs the compositor is offering it:


hyprctl monitors all -j | jq -r '.[] | "\(.name)\tdisabled=\(.disabled)"'

Do not create ~/.config/hypr/hyprpaper.conf on Omarchy 4. Nothing will read it.

**On bare Hyprland / Arch with hyprpaper**, the rest of the record is correct as written: add a wallpaper { monitor = ... } catch-all block with an empty monitor, reload with pkill hyprpaper; hyprpaper & disown or systemctl --user restart hyprpaper.service, set a live output with hyprctl hyprpaper wallpaper 'DP-3, /home/you/Pictures/wall.jpg, cover', verify with hyprctl hyprpaper listactive, and autostart the socat monitoradded listener. Restart Waybar with pkill waybar; waybar & disown or systemctl --user restart waybar.service.

**Drop the #154 attribution on the parse-failure paragraph.** The advice itself is still worth keeping. Run hyprpaper in the foreground and read the first lines, because a config that fails to parse leaves every output without a target:


pkill hyprpaper; hyprpaper 2>&1 | head -20

Just don't cite #154 for it. That issue is a user on the pre-1.0 wallpaper = monitor,path syntax, and the answer there was to update hyprpaper and hyprlang.

Verify

hyprctl hyprpaper listactive lists every name from hyprctl monitors -j | jq -r '.[].name'. The bar should be visible on the new display without a Hyprland restart.

Sources

no-wallpaper-or-bar-on-hotplugged-monitor