Fix Lua keybindings that do nothing, or launch the app at reload instead of on keypress
Cause confirmed in the v0.56.2 source. In LuaBindingsDispatcherUtils.cpp, hl.dsp.* factories wrap a function in an HL.Dispatcher userdata, and calling one only builds that object. pushDispatcherFunction accepts only a Lua function or that userdata, so nil and plain strings fail. hlBind then calls Internal::configError, which in LuaBindingsInternal.cpp reports the error and returns 0 without raising, so loading continues. The wiki dispatchers page states verbatim that hl.dsp.whatever() on its own does nothing. The stub /usr/share/hypr/stubs/hl.meta.lua confirms exec_cmd fun(cmd, rules?): nil. The float action "set" is accepted (LuaBindingsDispatchers.cpp line 749), HL.Window has a class field, and o.bind in default/hypr/helpers.lua wraps strings in hl.dsp.exec_cmd. hyprctl -j binds shows "dispatcher": "__lua". Defect: the fix binds SUPER+X, which Omarchy 4.0.4 already binds to 'Universal cut' (default/hypr/bindings/clipboard.lua:47). hl.bind adds a second bind and does not replace the first, so on Omarchy both fire and the window toggles while a CTRL+X is sent to the app. The Omarchy branch now unbinds first. Not exercised live.
hyprctl dispatch runs the action immediately on the live session. Test something harmless, not hl.dsp.exit().
Symptom
A keybinding I wrote with a Lua function does nothing when pressed, with no error, for example hl.bind("SUPER + X", function() hl.dsp.window.float({ action = "toggle" }) end). Or kitty opens by itself every time I save the config, and the bind I meant for it errors with hl.bind: dispatcher must be a dispatcher (e.g. hl.dsp.window.close()) or a lua function. Same error for hl.bind("SUPER + Q", "kitty").
Cause
Hyprland 0.56 has two families of functions that look alike.
hl.dsp.*functions (hl.dsp.exec_cmd,hl.dsp.window.close,hl.dsp.focus, ...) only build a dispatcher object. The wiki dispatchers page says plainly that writinghl.dsp.whatever()on its own does nothing. Inside a bind function each one has to be passed tohl.dispatch(...).hl.exec_cmd(cmd)runs the command right now and returns nothing (exec_cmd fun(cmd, rules?): nilin/usr/share/hypr/stubs/hl.meta.lua).
So hl.bind("SUPER + E", hl.exec_cmd("kitty")) launches kitty while the config loads, on every reload, and then hands hl.bind a nil. hl.bind accepts only a Lua function or a dispatcher object. Internal::pushDispatcherFunction in src/config/lua/bindings/LuaBindingsDispatcherUtils.cpp rejects anything else, including a plain command string, and hlBind reports the error above. That is a type error, so loading continues and only that bind is missing.
Fix
**A bind with one action:** pass the dispatcher object directly.
hl.bind("SUPER + E", hl.dsp.exec_cmd("kitty")) -- not hl.exec_cmd
hl.bind("SUPER + X", hl.dsp.window.float({ action = "toggle" }))
**A bind with logic or several actions:** wrap each dispatcher in hl.dispatch.
hl.bind("SUPER + X", function()
local w = hl.get_active_window()
if w ~= nil and w.class == "htop" then
hl.dispatch(hl.dsp.window.float({ action = "set" }))
else
hl.dispatch(hl.dsp.window.float({ action = "toggle" }))
end
end)
hl.exec_cmd("cmd") is correct inside a bind function or a hyprland.start handler, where running immediately is what you want.
**Omarchy 4:** SUPER+X is already Omarchy's "Universal cut" bind. hl.bind adds a bind and does not replace one, so unbind the default first or both actions fire. o.bind in /usr/share/omarchy/default/hypr/helpers.lua accepts a command string and wraps it in hl.dsp.exec_cmd for you, which is why the shipped ~/.config/hypr/bindings.lua examples pass strings:
-- ~/.config/hypr/bindings.lua
o.bind("SUPER + SHIFT + R", "SSH", "alacritty -e ssh your-server")
hl.unbind("SUPER + X") -- Omarchy's "Universal cut"
o.bind("SUPER + X", "Float", hl.dsp.window.float({ action = "toggle" }))
Check whether a key is already taken before you bind it:
omarchy menu keybindings --print | grep -E '^SUPER \+ X '
**Try a dispatcher before binding it:**
hyprctl dispatch 'hl.dsp.window.float({ action = "toggle" })'
Verify
hyprctl configerrors has no hl.bind lines, saving the config no longer opens a window by itself, and pressing the key performs the action. The bind appears in hyprctl -j binds with "dispatcher": "__lua". The type rules were read from the 0.56.2 source and the stub file on this machine. Not exercised live.
Sources
- https://wiki.hypr.land/configuring/core/dispatchers/
- https://github.com/hyprwm/hyprland-wiki/blob/main/content/configuring/core/advanced-configuration/lua-utilities.md
- https://github.com/hyprwm/Hyprland/blob/v0.56.2/src/config/lua/bindings/LuaBindingsToplevel.cpp
- https://github.com/hyprwm/Hyprland/blob/v0.56.2/src/config/lua/bindings/LuaBindingsDispatcherUtils.cpp
- https://github.com/omacom/omarchy/blob/quattro/default/hypr/helpers.lua
- https://github.com/omacom/omarchy/blob/quattro/config/hypr/bindings.lua
- https://github.com/omacom/omarchy/blob/quattro/default/hypr/bindings/clipboard.lua