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

Clear the wall of config errors after the Hyprland windowrule syntax overhaul

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

The syntax analysis is correct and verified. hypr.land/news/update53 confirms the windowrule grammar was 'completely overhauled' in 0.53. The 0.54 archived wiki shows windowrule = match:class my-window, border_size 10 and layerrule = blur on, match:namespace waybar (both orderings are accepted). Every snake_case rename in the table is confirmed against the current effects tables (no_focus, no_blur, no_anim, no_screen_share, suppress_event, border_color, scroll_touchpad, stay_focused, keep_aspect_ratio, max_size, min_size, render_unfocused, idle_inhibit, dim_around, nearest_neighbor, force_rgbx, pseudo, border_size). Cited issue #4023 is real and quotes these exact errors on Omarchy 3.2.3 / Hyprland 0.53.0-2. The Omarchy remedy is the defect: I read bin/omarchy-refresh-hyprland and bin/omarchy-refresh-config, and refresh-hyprland ONLY overwrites ~/.config/hypr/*.lua from $OMARCHY_PATH/config. It never touches $OMARCHY_PATH/default/hypr/, which is where the erroring files in the symptom live. So it cannot fix this class of error. omarchy-channel-set stable is also a no-op for someone already on stable. The correct action is omarchy-update. Also note the record shows *.lua in a 0.53-era (hyprlang/.conf) scenario, which is anachronistic.

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

On Omarchy, editing files under ~/.local/share/omarchy/default/ or /usr/share/omarchy/ works until the next update silently reverts them. Put overrides in ~/.config/hypr/ instead. Switching package channels (stable/rc/edge/dev) changes which Hyprland version pacman installs and can move you to an untested set. A channel switch plus reboot is the intended flow, not a partial upgrade.

Symptom

After an update, dozens of red 'Config error' lines cover the top of the screen at login, e.g. Config error in file /home/vs/.local/share/omarchy/default/hypr/apps/hyprshot.conf at line 2: invalid field selection: missing a value, invalid field noscreenshare: missing a value, invalid field class:^(1[p|P]assword)$: missing a value, followed by (47 more...). Windows open in the wrong place, nothing floats any more.

Cause

Hyprland 0.53 (Dec 2025) completely rewrote the window-rule and layer-rule grammar. The old form put the rule first and the matcher second (windowrule = float, class:foo). The new form requires explicit match: props (windowrule = match:class foo, float). Every old-syntax line is parsed as an unknown field, hence 'invalid field <x>: missing a value'. windowrulev2 is gone entirely. Distro/desktop config packs that still ship pre-0.53 rules produce one error per rule line.

Fix

Rewrite every rule using the mechanical transformation shown (that part is correct and verified against the 0.54 wiki). But replace the Omarchy section: the erroring files live under the package-owned defaults tree ($OMARCHY_PATH/default/hypr/, i.e. ~/.local/share/omarchy/default on 3.x, /usr/share/omarchy/default on 4.x). omarchy-refresh-hyprland only rewrites ~/.config/hypr/ from $OMARCHY_PATH/config and will NOT clear these errors. Use:


omarchy-channel-current      # informational
omarchy-update               # THIS is what ships corrected defaults
hyprctl configerrors         # confirm they are gone

Only reach for omarchy-refresh-hyprland if the remaining errors point at files under ~/.config/hypr/ (your own configs), and note it backs yours up as *.bak.<epoch>. Do not hand-edit the defaults tree. It is replaced on every update.

Verify

hyprctl configerrors prints nothing, and the red error bar is gone after hyprctl reload.

Sources

windowrule-syntax-overhaul-053-invalid-field