Fix a Lua config getter that hangs the keybindings menu or eats all memory
Checked on this workstation (omarchy 4.0.2-1, hyprland 0.56.2-1, lua 5.5.1) and against Hyprland v0.56.2 source. The mechanism is CONFIRMED here, not inferred: I copied the stub out of /usr/share/omarchy/bin/omarchy-menu-keybindings into a scratch script and ran it, and ipairs over it passed 1,000,000 iterations without reaching nil while #stub was 0, so the record's guard genuinely works. The scanner path is CONFIRMED: build_lua_bind_cache() runs pcall(dofile, "$HOME/.config/hypr/hyprland.lua") in a bare lua with hl set to a table whose metatable __index returns a callable, indexable noop, and pcall does not interrupt a loop. SUPER + K is bound to omarchy-menu-keybindings at /usr/share/omarchy/default/hypr/bindings/utilities.lua:10. The getters are CONFIRMED registered in src/config/lua/bindings/LuaBindingsQuery.cpp and the events hyprland.start, monitor.added and monitor.layout_changed in the wiki source, so the fix's API calls are real. The cited issue omacom/omarchy#7025 is open and does support the claim, including the memory exhaustion. Five corrections. The cause named three getters when the stub misses every one of the twenty or so hl.get_* functions, which a second reporter on the issue confirmed independently using hl.get_windows(). The cause left the compositor's immunity unexplained: LUA_TIMEOUT_CONFIG_RELOAD_MS = 1500 in src/config/lua/ConfigManager.hpp plus guardedPCall's instruction-count watchdog is why hyprctl reload stays clean, which is what a reader needs to stop suspecting Hyprland. The amplification was missing, and it is the reason this reaches OOM rather than staying a hang. The grep only covered three names and only ~/.config/hypr, missing ~/.local/state/omarchy/ which Omarchy's bootstrap.lua also puts on package.path. The verify was unreliable because omarchy 4.0.2 added a scan cache at ~/.cache/omarchy/keybindings-<sha>.records, which exists on this machine and is dated 29 August, so a reader can get a clean --print from a stale file. Severity raised from medium to high: the documented consequence is a kernel OOM that takes the session down and reboots the machine, which is not a medium-severity outcome even if the trigger is uncommon. Frequency left at occasional, because no file under /usr/share/omarchy/default/hypr/ iterates a getter at load time (grep found only hl.get_active_window() and hl.get_config(), both inside functions), so a stock machine never trips it. The source URL was corrected: https://github.com/basecamp/omarchy/issues/7025 returns a plain 404 to a browser, because GitHub's rename redirect covers the repository root but not the issue path, even though gh issue view -R basecamp/omarchy still resolves it through the API. NOT exercised: I did not reproduce the hang end to end, because that means writing a loop into ~/.config/hypr on the operator's daily workstation and risking the OOM the record describes. The stub behaviour was reproduced in isolation instead, and the scanner, the bindings and the cache were read on disk.
If the loop body allocates, each hung lua grows without bound, and every press of SUPER+K starts another one because the menu never appears to tell you the first failed. The upstream report reached 63 lua processes holding about 56 GB, a kernel global OOM, an OOM-killed Hyprland session and a reboot, in roughly two minutes on a 64 GB machine. Test config changes with a TTY available (CTRL + ALT + F2) and kill the runaway processes with pkill -x lua rather than pressing the key again.
Symptom
omarchy-menu-keybindings (SUPER+K) never opens: no menu, no error, no timeout. omarchy-menu-keybindings --print hangs forever. In worse cases the machine runs out of memory and freezes. Hyprland itself is fine: hyprctl reload and hyprctl configerrors are clean.
Cause
Iterating any hl.* getter with ipairs at config-evaluation time. Omarchy's keybinding scanner (build_lua_bind_cache() in /usr/share/omarchy/bin/omarchy-menu-keybindings) re-evaluates ~/.config/hypr/hyprland.lua in a bare lua interpreter with hl replaced by a stub. The stub implements only hl.bind, hl.dsp and hl.get_config, and answers every other key through a __index metamethod that returns a noop table which is itself indexable and callable. So hl.get_monitors() returns noop, and ipairs(noop) reads index 1, 2, 3 and never hits nil. That is the whole family, not three names: Hyprland 0.56.2 registers get_windows, get_window, get_active_window, get_urgent_window, get_workspaces, get_workspace, get_active_workspace, get_monitors, get_monitor, get_layers, get_workspace_windows and more, and the stub covers none of them. Hyprland itself is unaffected because the compositor evaluates the config under a watchdog that aborts after 1500 ms, and inside the real compositor the getters return real tables anyway. Only the scanner subprocess spins. Two things make it worse than a hang. If the loop body allocates, for example table.insert, that lua process grows without bound. And because the menu never appears, pressing SUPER+K again starts another one, so the leak compounds: the upstream reporter accumulated 63 lua processes holding about 56 GB, hit a kernel global OOM, and the machine rebooted. Still unfixed in omarchy 4.0.2-1.
Fix
Move the iteration out of load time and into an event handler, so it only runs inside the real compositor.
Instead of:
-- ~/.config/hypr/monitors.lua -- HANGS the bind scanner
for _, m in ipairs(hl.get_monitors()) do
-- ...
end
write:
hl.on("hyprland.start", function()
for _, m in ipairs(hl.get_monitors()) do
-- ...
end
end)
-- react to hotplug:
hl.on("monitor.added", function(monitor)
-- ...
end)
-- "hyprland.start" fires once per compositor start, so if the work also has to
-- survive a `hyprctl reload`, hook the arrangement event too:
hl.on("monitor.layout_changed", function()
-- ...
end)
If you must run it at load, guard it. The stub has no __len, so #stub is 0 and this skips:
local mons = hl.get_monitors()
if type(mons) == "table" and #mons > 0 and #mons < 64 then
for i = 1, #mons do local m = mons[i] end
end
A guard that names the stub directly works for any getter. Real getters return a plain table, the stub returns one that is also callable:
local function real_list(value)
local mt = type(value) == "table" and getmetatable(value) or nil
if type(value) ~= "table" or (mt and mt.__call) then return {} end
return value
end
for _, m in ipairs(real_list(hl.get_monitors())) do
-- ...
end
Find the offender. Search every file the config can reach, not just hyprland.lua, because Omarchy's bootstrap puts ~/.local/state, ~/.config and $OMARCHY_PATH on package.path, and a third-party module such as shezdy/hyprsplit iterates all three list getters in its own init.lua:
grep -rn 'hl\.get_' ~/.config/hypr/ ~/.local/state/omarchy/
Then look at each hit and ask whether it is inside an hl.on(...) callback or at top level. Only top-level calls hang.
Recovery while it is hung: the runaway processes are ordinary user processes, so kill them from a TTY (CTRL + ALT + F2) or any terminal before the machine runs out of memory.
pkill -f omarchy-menu-keybindings
pkill -x lua
Verify
Clear the cache first, because omarchy 4.0.2 caches the scan in ~/.cache/omarchy/keybindings-<sha>.records and a stale file makes a still-broken config look fixed.
rm -f ~/.cache/omarchy/keybindings-*.records
timeout 30 omarchy-menu-keybindings --print | wc -l
It returns a list of bindings and exits instead of hanging. A timeout exit status of 124 means it is still hung.
Sources
- https://github.com/omacom/omarchy/issues/7025
- https://github.com/hyprwm/Hyprland/blob/v0.56.2/src/config/lua/bindings/LuaBindingsQuery.cpp
- https://github.com/hyprwm/Hyprland/blob/v0.56.2/src/config/lua/ConfigManager.hpp
- https://github.com/hyprwm/Hyprland/blob/v0.56.2/src/config/lua/ConfigManager.cpp
- https://github.com/hyprwm/hyprland-wiki/blob/main/content/configuring/core/advanced-configuration/events.md