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

Fix Lua keybindings that do nothing, or launch the app at reload instead of on keypress

omarchyarchhyprlandwayland
CORRECTED An auditor found the fix wrong or incomplete and rewrote it. · checked against Omarchy omarchy 4.0.4-1 on 2026-10-05
AUDIT NOTE

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.

The cause above was not rewritten and may still contain the error described. The fix below is the corrected version.
RISK

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 writing hl.dsp.whatever() on its own does nothing. Inside a bind function each one has to be passed to hl.dispatch(...).
  • hl.exec_cmd(cmd) runs the command right now and returns nothing (exec_cmd fun(cmd, rules?): nil in /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

lua-bind-function-hl-dsp-not-dispatched