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

Fix a Lua config getter that hangs the keybindings menu or eats all memory

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

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.

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

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

lua-config-getters-infinite-loop-at-load