Get out of Hyprland emergency mode when a Lua error registered no binds
Checked on this Omarchy 4 workstation (omarchy 4.0.2-1, omarchy-settings 4.0.2-1, hyprland 0.56.2-1) and against Hyprland v0.56.2 source fetched from hyprwm/Hyprland. Emergency mode is real and still called that: src/config/lua/Emergency.hpp holds the EMERGENCY_PCALL Lua block, and the same strings are in the shipped /usr/bin/Hyprland binary, so the escape route is confirmed on this machine and not only in the source. The binds are SUPER + Q which launches the first installed of kitty, alacritty, foot, wezterm, gnome-terminal, xterm, SUPER + R which launches hyprland-run, and SUPER + M which exits. That list is the whole escape route and the record never gave it, so a reader could not tell whether SUPER + Q would do anything: on stock Omarchy 4 it does, because foot is at line 41 of /usr/share/omarchy/install/omarchy-base.packages and hyprland-run is owned by hyprland-guiutils 0.2.2-2. The record's cause sentence about "require() scope protection" does not describe anything in the code, so I replaced it with the real sequence from src/config/lua/ConfigManager.cpp, where phase 1 only runs luaL_loadfile on the main config path and the runtime error lands after clearKeybinds(). The log path held: $XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log is the live path here, but HYPRLAND_INSTANCE_SIGNATURE is absent from a text console or a plain ssh shell, so I added the wiki's newest-instance form for a reader who has no session terminal. The manual hyprctl eval pause and resume pair is mis-specialised to Omarchy: /usr/share/omarchy/bin/omarchy-hyprland-reload-guard does the same job, saves and restores the prior values under /run/omarchy/hyprland-reload-guard/, and is already wired to /usr/share/libalpm/hooks/10-omarchy-hyprland-reload-pause.hook and 90-omarchy-hyprland-reload-resume.hook, all three read on this machine. The omarchy-refresh-hyprland step was the worst advice on the record: read at /usr/share/omarchy/bin/omarchy-refresh-hyprland, it overwrites seven files in ~/.config/hypr through omarchy-refresh-config and touches nothing under /usr/share/omarchy, so it cannot fix the cited mid-transaction cause and it destroys user overrides, recoverable only from .bak.<epoch> copies. I confirmed omarchy update itself never calls it, and that the migrations under /usr/share/omarchy/migrations/ patch hyprland.lua surgically rather than replacing it, so neither the record's edits nor the pcall wrapper are transient. Issue 8637 was read in full on omacom/omarchy: it describes exactly this record's scenario, names the pause hook, and is still open as of 2026-09-13, so the trigger is current. The basecamp URL on the record 404s for an anonymous fetch, so it is removed in favour of the omacom one. NOT exercised: I did not induce emergency mode, break a config, run hyprctl reload, or press any emergency bind, because this is the operator's daily workstation, so the bind behaviour is confirmed from source and from strings in the installed binary rather than by tripping it.
debug:suppress_errors = true hides real config errors, the emergency banner included, so turn it back off when you are done. The emergency binds still register while it is on, but nothing on screen tells you the config is broken. Do not reboot to clear this while a pacman transaction is still running, because you can end up with a half applied upgrade. omarchy-refresh-hyprland overwrites seven files in ~/.config/hypr with the Omarchy defaults and keeps only timestamped .bak copies of your versions.
Symptom
A banner sits on top of every workspace: Emergency mode tripped: A lua config error resulted in no binds being registered. Emergency binds active: SUPER + Q -> any known terminal, SUPER + R -> hyprland-run, SUPER + M -> Exit followed by Your config has errors: and a Lua stack traceback such as cannot open /usr/share/omarchy/default/hypr/bootstrap.lua: No such file or directory. None of your normal keybindings work.
Cause
Hyprland 0.56.2 trips emergency mode when a config reload finishes with at least one error and zero keybinds registered. The test is in src/config/lua/ConfigManager.cpp: const bool emergencyModeTripped = !m_errors.empty() && g_pKeybindManager->m_keybinds.empty();. Only the main config file is syntax checked before anything is torn down. The reload then clears every keybind, resets the Lua state, and runs the config under a protected call, so a require() or dofile() of a path that does not exist raises at that point, after the old binds have already gone. On Omarchy 4 the first executable line of ~/.config/hypr/hyprland.lua is dofile((os.getenv("OMARCHY_PATH") or "/usr/share/omarchy") .. "/default/hypr/bootstrap.lua"), so one missing file under /usr/share/omarchy takes the whole config down. The usual triggers are a typo in a require() path, a syntax error early in hyprland.lua, and a file that vanishes for a moment while pacman replaces the package that owns it during omarchy update.
Fix
Emergency mode registers three binds of its own, so you are not locked out:
SUPER + Qlaunches the first ofkitty,alacritty,foot,wezterm,gnome-terminal,xtermthat is installed.SUPER + Rlauncheshyprland-run.SUPER + Mexits Hyprland.
On a stock Omarchy 4 install foot is listed in /usr/share/omarchy/install/omarchy-base.packages and hyprland-run comes from the hyprland-guiutils package, so the first two both work. If none of those six terminals is installed, switch to a text console with Ctrl + Alt + F2 and log in there instead.
Read the actual error. From a terminal inside the session:
hyprctl configerrors
tail -n 200 "$XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log"
From a text console or over ssh HYPRLAND_INSTANCE_SIGNATURE is not set, so pick the newest instance directory:
tail -n 200 "$XDG_RUNTIME_DIR/hypr/$(ls -t "$XDG_RUNTIME_DIR/hypr/" | head -n 1)/hyprland.log"
If the file was missing only while pacman was replacing it, let omarchy update finish, then reload once:
hyprctl reload
If a module really is optional, wrap it so it cannot take the config down:
local ok, err = pcall(require, "maybe-nonexistent")
if not ok then
hl.notification.create({ text = "skipped module: " .. tostring(err), timeout = 4000 })
end
Omarchy ships a helper that does the same check up front, /usr/share/omarchy/default/hypr/require_optional.lua:
local require_optional = require("default.hypr.require_optional")
require_optional.module("maybe-nonexistent")
To stop reloads firing during a package transaction, use the shipped guard rather than a raw hyprctl eval:
omarchy-hyprland-reload-guard pause
# ... run the transaction ...
omarchy-hyprland-reload-guard resume
Omarchy 4 already runs that pair automatically around any omarchy-settings upgrade, through /usr/share/libalpm/hooks/10-omarchy-hyprland-reload-pause.hook and 90-omarchy-hyprland-reload-resume.hook. The guard saves the previous values of misc.disable_autoreload and debug.suppress_errors under /run/omarchy/hyprland-reload-guard/ and restores them, where a hand written hyprctl eval pair turns both off whatever they were set to before.
Last resort, and only when the broken file is one of your own:
omarchy-refresh-hyprland
hyprctl reload
That replaces all seven of ~/.config/hypr/.luarc.json, autostart.lua, bindings.lua, input.lua, looknfeel.lua, hyprland.lua and monitors.lua with the Omarchy defaults, keeping each old file as <name>.bak.<epoch>. It touches nothing under /usr/share/omarchy, so it does not help when the missing file is a shipped default.
Verify
The emergency banner disappears, hyprctl configerrors is empty, and hyprctl binds lists your bindings again.