OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
hyprland-config medium very-common DISPUTE

hl.monitor() does nothing: wrong connector name, or a mode the driver never advertised

hyprlandomarchyarchendeavouroscachyosmanjarowaylandlaptopdesktop
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

Re-checked on this workstation (omarchy 4.0.2-1, hyprland 0.56.2-1, kernel 7.1.9-arch1-2) against the current Hyprland wiki markdown and against Hyprland's own source at tag v0.56.2, and found three claims that are stale or wrong plus one failure mode missing.

The Lua shape is correct and needed no change: every snippet already uses hl.monitor() with the output key, which matches /usr/share/omarchy/config/hypr/monitors.lua and the live ~/.config/hypr/monitors.lua on this machine, and matches the field table in content/configuring/core/monitors/_index.md. hyprctl eval as the live-test path is confirmed by hyprctl --help here and by the wiki's using-hyprctl page. The scaled-position rule, the inverted Y axis, the no-overlap rule, transform 0 to 7, mirror, disabled, the four mode keywords and the empty-output fallback all still hold. All three Omarchy binaries exist at /usr/share/omarchy/bin/ and default/hypr/bindings/utilities.lua line 32 and 33 bind exactly SUPER + CTRL + Delete and SUPER + CTRL + ALT + Delete as the record says.

What was wrong. First, the record said an unavailable mode is "rejected and the monitor falls back to preferred". src/output/Monitor.cpp at v0.56.2 does the opposite: lines 818 to 849 sort the driver's modes by closeness to the request and keep the best three, then push the exact requested numbers as a custom mode, and lines 878 to 965 take the first candidate that passes the atomic test. Only when all of them fail does it use any working mode and raise a five-second red notification. The practical result is the nearest available mode, which is what the reader is actually looking at. Second, the instruction to "DROP the trailing (DP-2) portname" from a desc: string is stale. Monitor.cpp line 254 and 255 build the short description as make, model and serial and the comment says it "excludes the parenthesized DRM node name suffix", and matchesStaticSelector at line 1201 prefix-matches the selector against both forms. Confirmed live: hyprctl monitors all here prints description: Microstep MSI G274QPF CC2H634102253 with no port name to remove, so the old instruction sends the reader looking for text that is not there. Third, the record said an invalid scale is refused with a warning. Monitor.cpp lines 997 to 1050 search plus or minus 90 steps of 1/120 for the nearest scale giving whole logical pixels and apply that instead, notifying with both numbers, and only log Invalid scale passed to monitor, <n> failed to find a clean divisor when the search fails. Omarchy's own omarchy-hyprland-monitor-scaling implements the same 1/120 gcd rounding, which corroborates it.

Added a fourth cause the record missed and Omarchy documents: a display powered off at boot returns a partial EDID with no modes, the output comes up at 0x0 and the screen stays black. /usr/share/omarchy/bin/omarchy-hyprland-monitor-modeless exists solely to detect that state and its header comment says so.

Also corrected the danger. omarchy-hw-recover-internal-monitor was presented as the recovery for a self-inflicted disabled = true. Reading /usr/bin/omarchy-hw-recover-internal-monitor shows it only removes ~/.local/state/omarchy/toggles/hypr/internal-monitor-disable.lua when no external monitor is attached, so it cannot undo a hand-written rule. Corrected the verify for the same reason the cause was wrong: hyprctl configerrors stays empty for both the mode fallback and the scale correction, so it is not the check to rely on, and it now uses monitors all so a mirrored or disabled output is visible.

Not exercised. Nothing was written and no mode or scale was changed, because this is the operator's daily workstation driving a real panel. The fallback and notification paths were read from the v0.56.2 source rather than triggered, and the invalid-scale path was not run. The desc: selector was not tested against a live rule, only read from matchesStaticSelector. misc:disable_autoreload reads bool: false, set: false here, so auto-reload is on by default, but a save-triggered reload was not observed.

Swapped the four basecamp/omarchy blob URLs for omacom/omarchy, the current name. The old ones still redirect, but every path was re-fetched against omacom/omarchy@quattro for this audit and that is the name the search API resolves.

The cause above was rewritten on 2026-09-13 to match this note; the fix was corrected by the audit itself.
RISK

disabled = true does not just blank the screen. It removes the output from the layout and migrates all of its windows and workspaces onto the remaining monitors. Disabling your only display leaves you with no way back except Ctrl+Alt+F2 to a TTY, then:


hyprctl -i 0 eval 'hl.monitor({ output = "eDP-1", disabled = false })'

or edit monitors.lua and reboot. Use the dpms dispatcher if you only want the panel powered off. On Omarchy, omarchy-hw-recover-internal-monitor recovers only from Omarchy's own omarchy-hyprland-monitor-internal toggle: it deletes ~/.local/state/omarchy/toggles/hypr/internal-monitor-disable.lua when no external monitor is connected. It does nothing about a disabled = true you wrote into monitors.lua yourself.

Symptom

"My monitor config is just ignored." hl.monitor({ output = "HDMI-A-1", mode = "1920x1080@144", position = "0x0", scale = 1 }) sits in monitors.lua, the file saves, no error appears in hyprctl configerrors, and the display still runs at 60 Hz, or at 1366x768, or the external screen never lights up at all. Sometimes instead you get an on-screen warning about overlapping monitors, or "Invalid scale passed to monitor".

Cause

Four separate failures all present as "the rule did nothing", and only one of them ever produces a config error.

(1) The output string does not match a real connector. Names are assigned by the kernel and shift between boots, docks and GPUs, so a monitor on HDMI-A-2 will never be touched by a rule for HDMI-A-1, and a rule naming an output that does not exist is silently inert.

(2) The mode is not one the driver reports, and Hyprland does not simply give up. On 0.56.2 it sorts the driver's mode list by closeness to what you asked for, keeps the best three, and if none of them is within one pixel and one Hz of the request it also pushes your exact numbers as a custom DRM mode. The first candidate that passes the atomic modeset test wins. Asking for 2560x1440@140 on a panel that only offers 144 and 120 therefore lands you on 144 or 120, with nothing in hyprctl configerrors, which reads as "my line was ignored". Only if every candidate fails does Hyprland fall through to any mode that works and raise a red on-screen notification for five seconds. As the maintainer put it: "if the mode is not listed in hyprctl monitors there's nothing hyprland can do. Custom modelines might or might not work. It's all down to the driver."

(3) The scale does not divide the resolution into whole logical pixels. 1920x1080 / 1.5 = 1280x720 is fine, 1920x1080 / 1.4 = 1371.43x771.43 is not. Hyprland does not refuse the value. It searches up to 90 steps of 1/120 either side for the nearest scale that divides cleanly, applies that one instead, and shows a notification naming both the value you wrote and the value it used. Only when no clean divisor exists in that window does it log Invalid scale passed to monitor, <n> failed to find a clean divisor and revert the output to its default scale. Either way you end up on a scale you did not ask for.

(4) The panel was powered off when Hyprland started. A sleeping display answers with a partial EDID carrying no video modes at all, so Hyprland brings the output up at 0x0 and the screen stays black while the output is still listed as enabled. Nothing fires an event for this state. Omarchy ships omarchy-hyprland-monitor-modeless to detect it.

Plain hyprctl monitors also hides disabled outputs and mirrors, so the connector you need may not appear in the list you are reading.

Fix

First, get the truth from the compositor. all is load-bearing, because plain hyprctl monitors omits disabled and mirrored outputs:


hyprctl monitors all          # every output, plus every mode the driver actually offers
hyprctl -j monitors all | jq  # same thing, easier to grep

If an output is listed, disabled: false, and reports a size of 0x0, the panel was asleep at boot and handed the kernel an EDID with no modes. Wake it and replug the cable. On Omarchy there is a check for exactly this:


omarchy-hyprland-monitor-modeless   # exit 0 = an enabled monitor has no mode

Otherwise copy the connector name and one of the listed availableModes entries verbatim into ~/.config/hypr/monitors.lua (Omarchy) or ~/.config/hypr/hyprland.lua (plain Hyprland):


-- Exact name, and a mode that appears in `hyprctl monitors all`
hl.monitor({ output = "DP-2", mode = "2560x1440@143.97", position = "0x0", scale = 1 })

-- Connector names shuffle between docks and boots. Match the EDID description
-- instead. Copy the `description:` line from `hyprctl monitors` exactly as it
-- is printed: on 0.56 that line is already the make, model and serial with no
-- port name appended, so there is nothing to strip. Matching is a prefix test,
-- so a shortened description still selects the monitor.
hl.monitor({ output = "desc:Dell Inc. DELL U2720Q 8FGZ043", mode = "highrr", position = "auto", scale = 1 })

-- Stop guessing modes. preferred = EDID preferred, highres = highest resolution,
-- highrr = highest refresh rate, maxwidth = widest mode. They cannot be combined.
-- An empty output is the catch-all fallback. Keep it LAST in the file.
hl.monitor({ output = "", mode = "preferred", position = "auto", scale = "auto" })

-- Rotated panel: 0 normal, 1 = 90 deg, 2 = 180, 3 = 270, 4-7 = flipped variants
hl.monitor({ output = "DP-3", mode = "preferred", position = "auto", scale = 1, transform = 1 })

-- Mirror the laptop panel onto an external (mirrors do NOT show in plain `hyprctl monitors`)
hl.monitor({ output = "HDMI-A-1", mode = "preferred", position = "0x0", scale = 1, mirror = "eDP-1" })

-- Remove an output from the layout entirely
hl.monitor({ output = "eDP-1", disabled = true })

Try a rule live before committing it to a file. Under a Lua config this is eval, not keyword:


hyprctl eval 'hl.monitor({ output = "DP-2", mode = "2560x1440@143.97", position = "0x0", scale = 1 })'

Positions are in **scaled** pixels: a 3840-wide monitor at scale 2 occupies 1920 logical px, so the next monitor starts at 1920x0, not 3840x0. Y is inverted, so negative y is up. No two monitors may overlap, and an overlapping pair is refused with a warning rather than registered.

Hyprland watches the config file and reloads it when you save, unless misc:disable_autoreload is set, so a monitors.lua edit applies with no logout. Force it with hyprctl reload if you want to be sure.

On Omarchy 4 use the shipped tooling instead of hand-editing where one exists:


omarchy-hyprland-monitor-scaling 1.6      # rounds to the nearest scale that divides cleanly,
                                          # applies it, and writes both the monitor scale and
                                          # GDK_SCALE back into ~/.config/hypr/monitors.lua
omarchy-hyprland-monitor-internal-mirror toggle   # SUPER + CTRL + ALT + Delete
omarchy-hyprland-monitor-internal toggle          # SUPER + CTRL + Delete

omarchy-hyprland-monitor-scaling only rewrites the file while it still carries Omarchy's generic catch-all shape. Once you have replaced that with per-output rules it changes the live scale and leaves the file alone, so the setting is lost on the next reload.

Verify


hyprctl -j monitors all | jq -r '.[] | "\(.name) \(.width)x\(.height)@\(.refreshRate) scale=\(.scale) disabled=\(.disabled)"'

reports the connector, resolution, refresh rate and scale you asked for. Use all, because a mirrored or disabled output is absent from the plain list. Do not use hyprctl configerrors as the test here: a mode that could not be set and a scale that was silently corrected both leave it empty, and both announce themselves as a red on-screen notification instead. If the numbers come back different from what you wrote, that is the closest-mode or nearest-clean-scale fallback doing its job, not a typo in your file.

Sources

monitor-config-ignored-name-or-mode