Fix submaps after the Lua migration: hl.submap is nil, or the submap keys fire everywhere
Read hlBind and hlDefineSubmap in Hyprland v0.56.2 src/config/lua/bindings/LuaBindingsToplevel.cpp: define_submap sets m_currentSubmap, pcalls fn, restores the previous submap, hlBind stamps kb.submap from it, and catchall outside a submap gives exactly the quoted error. The 0.56.2 stub /usr/share/hypr/stubs/hl.meta.lua (owned by hyprland 0.56.2-2) has define_submap at top level and submap only under hl.dsp, so hl.submap is nil. The wiki submaps page (hyprwm/hyprland-wiki content/configuring/core/binds/submaps.md) matches the fix, the optional reset second argument, submap_universal, and the --instance 0 recovery in danger. ALT+R is not bound by any file in /usr/share/omarchy/default/hypr/bindings/ on 4.0.4-1. Two defects in the commands. The diagnostic grep looked for '"key": "Right"', but hyprctl -j binds reports the key as written in the bind string, so a bind written "right" never matches a case-sensitive grep. And omarchy menu keybindings --print | grep -i 'alt.*r' returned 59 lines on this machine, because the --print format is 'SUPER SHIFT + RETURN -> ...' and almost every line with ALT matches, so it cannot confirm the key is free. The verify said 'none with an empty submap', but every global bind has submap "" (confirmed in hyprctl -j binds output here). Cause holds. Not exercised live: no submap was defined or entered.
A submap with no escape (or other hl.dsp.submap("reset")) bind leaves the keyboard with no working binds once entered. Recovery is hyprctl dispatch 'hl.dsp.submap("reset")' from an open terminal, or from a TTY with hyprctl dispatch --instance 0 'hl.dsp.submap("reset")'.
Symptom
After converting my resize submap to Lua, either the config errors with attempt to call a nil value (field 'submap') and every bind below it in that file is missing, or the submap binds are active all the time: the arrow keys resize the focused window in every app, I cannot move the cursor in a text editor, Escape does nothing in apps, and hyprctl submap says default. Another variant: hl.bind: catchall keybinds are only allowed in submaps.
Cause
hyprlang opened a submap with the keyword submap = resize, listed binds, and closed it with submap = reset. Lua has no section markers. In Hyprland 0.56.2 a bind belongs to a submap only if hl.bind runs while hl.define_submap(name, fn) is executing fn: hlDefineSubmap in src/config/lua/bindings/LuaBindingsToplevel.cpp sets the current submap, calls fn, then restores the previous one, and hlBind stamps each bind with whatever submap is current at that moment.
So a literal translation fails two ways. hl.submap("resize") does not exist (the API has hl.define_submap to define one and the dispatcher hl.dsp.submap(name) to enter one), so the call raises a runtime error that aborts the rest of that file. Writing hl.dsp.submap("resize") on its own line as a section opener only builds a dispatcher object and discards it, so the right, left, up, down and escape binds that follow are registered in the global map and take those keys from every application. catchall is refused outside a submap for the same reason.
Fix
**Get your keys back now** if the arrows or Escape are hijacked. From a terminal (open one with SUPER+RETURN on Omarchy 4):
hyprctl submap # where you are
hyprctl -j binds | grep -i -B3 -A10 '"key": "right"' # check the "submap" field
An arrow bind with "submap": "" is global and is the leak. Fix the file and save, which reloads Hyprland.
**Write the submap with hl.define_submap.** On Omarchy 4 this goes in ~/.config/hypr/bindings.lua. On plain Arch, in ~/.config/hypr/hyprland.lua.
-- hyprlang:
-- bind = ALT, R, submap, resize
-- submap = resize
-- binde = , right, resizeactive, 10 0
-- bind = , escape, submap, reset
-- submap = reset
hl.bind("ALT + R", hl.dsp.submap("resize"))
hl.define_submap("resize", function()
hl.bind("right", hl.dsp.window.resize({ x = 10, y = 0, relative = true }), { repeating = true })
hl.bind("left", hl.dsp.window.resize({ x = -10, y = 0, relative = true }), { repeating = true })
hl.bind("up", hl.dsp.window.resize({ x = 0, y = -10, relative = true }), { repeating = true })
hl.bind("down", hl.dsp.window.resize({ x = 0, y = 10, relative = true }), { repeating = true })
hl.bind("escape", hl.dsp.submap("reset")) -- always give a way out
end)
-- binds below this line are global again
binde (repeat) becomes { repeating = true }. To leave the submap automatically after any bind inside it fires, pass "reset" as the second argument: hl.define_submap("launch", "reset", function() ... end). A bind that must work in every submap takes { submap_universal = true }. catchall is allowed only inside the function.
On Omarchy 4, check the key you pick is free, or hl.unbind it first. ALT + R is not used by Omarchy's defaults on 4.0.4. The --print list writes modifiers as ALT + R, so match the whole key at the start of the line:
omarchy menu keybindings --print | grep -E '^ALT \+ R ' # no output means the key is free
Verify
hyprctl -j binds shows the arrow and escape binds with "submap": "resize", and no bind for right, left, up or down with "submap": "" (global binds always show an empty submap, so only the arrow ones matter). Arrow keys work normally in an editor, ALT+R then Right resizes the window, and Escape returns hyprctl submap to default. The API shape was read from the 0.56.2 source, the 0.56.2 stub file and the wiki. Not exercised live.