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

Fix scripts failing with "')' expected near" from hyprctl dispatch

hyprlandomarchyarchwayland
AUDITED Audited against its sources and confirmed accurate. · checked against Omarchy omarchy 4.0.4-1 on 2026-10-05
AUDIT NOTE

The verbatim error, the Note line and exit code 7 appear in a comment on issue #7556 (Omarchy 4.0.2-1). The using-hyprctl wiki page says dispatch is shorthand for eval 'hl.dispatch(...)' and that eval returns ok or any error raised. The dispatchers wiki page says a bare hl.dsp.* call does nothing, which supports the second symptom. Every rewritten form in the table was cross-checked against dispatchers that Omarchy itself binds in /usr/share/omarchy/default/hypr/bindings/tiling.lua on 4.0.4-1: hl.dsp.window.close(), hl.dsp.layout("togglesplit"), hl.dsp.window.float({ action = "toggle" }), hl.dsp.window.fullscreen({ mode = "fullscreen" }) and hl.dsp.focus({ workspace = ... }). They are also on the dispatchers wiki page. Not exercised: no hyprctl dispatch was run here, by the brief's rule. Not confirmed: whether the error text goes to stdout or stderr.

Symptom

A script, keybinding helper or bar module that ran hyprctl dispatch workspace 3, hyprctl dispatch exec firefox or hyprctl dispatch layoutmsg togglesplit now fails with:


error: [string "return hl.dispatch(layoutmsg togglesplit)"]:1: ')' expected near 'togglesplit'
 → Note: dispatch in lua is a shorthand for hl.dispatch(...), your syntax might need to be updated.

and exit code 7. Or the opposite: hyprctl eval 'hl.dsp.focus({ workspace = "3" })' prints ok and nothing happens.

Cause

With a Lua config (Hyprland 0.55+, Omarchy 4), hyprctl dispatch <text> is shorthand for hyprctl eval 'hl.dispatch(<text>)', so the argument must be a Lua dispatcher expression, not the old dispatcher name and arguments. hl.dsp.* functions only build a description of an action. Evaluating one on its own, without hl.dispatch, does nothing and still returns ok.

Fix

Rewrite each call in the Lua form, single quotes outside so the inner double quotes survive the shell:


# old                                  # Lua config
hyprctl dispatch workspace 3            hyprctl dispatch 'hl.dsp.focus({ workspace = "3" })'
hyprctl dispatch exec firefox           hyprctl dispatch 'hl.dsp.exec_cmd("firefox")'
hyprctl dispatch killactive             hyprctl dispatch 'hl.dsp.window.close()'
hyprctl dispatch togglefloating         hyprctl dispatch 'hl.dsp.window.float({ action = "toggle" })'
hyprctl dispatch fullscreen             hyprctl dispatch 'hl.dsp.window.fullscreen({ mode = "fullscreen" })'
hyprctl dispatch layoutmsg togglesplit  hyprctl dispatch 'hl.dsp.layout("togglesplit")'

With eval, wrap the dispatcher yourself:


hyprctl eval 'hl.dispatch(hl.dsp.focus({ workspace = "3" }))'

Check results by exit code. A failed dispatch exits non-zero and prints error: on stdout:


out=$(hyprctl dispatch 'hl.dsp.focus({ workspace = "3" })') || echo "dispatch failed: $out" >&2

The full dispatcher list is on the Hyprland wiki Dispatchers page. A config still on hyprland.conf (hyprlang) is a different parser, so confirm which one you run before rewriting.

Verify

The rewritten command prints ok, exits 0, and the action happens.

Sources

hyprctl-dispatch-legacy-syntax-expected-near