Read hyprctl configerrors when one ~/.config/hypr/*.lua file breaks and half the config vanishes
Read Hyprland v0.56.2 src/config/lua/ConfigManager.cpp. Reload runs phase1Load (luaL_loadfile on the main file only) before clearing any state, and on failure records the error and returns, so the old config stays. safeLuaRequire pcalls the real require, rethrows errors starting module '<name>' not found with luaL_error, and otherwise adds require("<module>"): <err> to the error list and returns an empty table, so the caller continues. The main chunk runs under guardedPCall with a traceback handler, so an uncaught not-found error skips the rest of hyprland.lua. Emergency mode needs errors plus zero binds, matching the cross-reference, and the record hyprland-emergency-mode-no-binds-registered exists in the corpus. Omarchy side: /usr/share/omarchy/default/hypr/require_optional.lua uses package.searchpath and then a plain require, so it skips missing modules but still surfaces errors, as stated. Hyprland prepends the config dir to package.path (ConfigManager.cpp ~line 533), so the plain-Arch pcall(require, "extra") resolves ~/.config/hypr/extra.lua. luac is /usr/bin/luac from lua 5.5.1-1, a hyprland dependency. The log path exists here. Not reproduced live.
Symptom
After an edit, some of my settings apply and some do not. My own keybindings are gone but Omarchy's work, or my monitors and input are fine but nothing in autostart runs. The error bar shows something like require("hypr.bindings"): ... bindings.lua:14: unexpected symbol near ... or module 'hypr.bindigns' not found with a stack traceback. Sometimes the edit just does not take and the old behaviour stays.
Cause
Hyprland 0.56.2 handles three kinds of Lua error differently (src/config/lua/ConfigManager.cpp).
- **Syntax error in the main
hyprland.lua.** Every reload first runsluaL_loadfileon the main file only. If that fails, Hyprland records the error and keeps the old config running, so the edit just does not take. - **Error inside a file loaded with
require.** Hyprland replacesrequirewithsafeLuaRequire. A syntax or runtime error inside the required file is added to the error list asrequire("<module>"): <message>, an empty table is returned, and the caller carries on. On Omarchy 4 a typo in~/.config/hypr/bindings.luatherefore drops that file only: your binds and yourhl.unbindlines are gone, so Omarchy's defaults reappear on keys you had replaced, while monitors, input, look and autostart still load. A runtime error drops the rest of the file from the error line down. - **A module that cannot be found.**
safeLuaRequirerethrowsmodule '<name>' not foundas a real error in the calling file. If the typo is in arequire(...)line inhyprland.lua, everything below that line is skipped. On Omarchy 4 that includesrequire("default.hypr.toggles")and any rules you added at the bottom.
If an error leaves zero binds registered, emergency mode starts. That case has its own record, hyprland-emergency-mode-no-binds-registered.
Fix
**Read the errors, then match them to the three cases:**
hyprctl configerrors
require("hypr.<name>"): <file>:<line>: ...means one module failed. Fix the line it names in~/.config/hypr/<name>.lua. The other files loaded fine.module 'hypr.<name>' not foundmeans arequireline names a file that does not exist. Fix the spelling in~/.config/hypr/hyprland.luaor create the file. Everything after that line was skipped.- An error with no
require(...)prefix pointing athyprland.luaitself is in the main file.
**Check a file before saving it**, because Hyprland reloads on every save. luac is installed on Omarchy 4 with the lua package:
luac -p ~/.config/hypr/*.lua && echo syntax-ok
That catches syntax errors only. A call to something that does not exist, such as hl.set, is still a runtime error.
**Make an optional module unable to take the rest down.** Omarchy 4 ships a helper that skips a missing module but still reports errors inside one that exists:
local require_optional = require("default.hypr.require_optional")
require_optional.module("hypr.extra")
On plain Arch, use pcall:
local ok, err = pcall(require, "extra")
if not ok then print("skipped extra: " .. tostring(err)) end
**Read the log** for the full traceback when the bar truncates it:
grep -iE 'error|lua' "$XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log" | tail -n 40
Verify
hyprctl configerrors prints an empty list and luac -p ~/.config/hypr/*.lua prints nothing. Your binds are back in hyprctl -j binds. The three behaviours were read from the 0.56.2 ConfigManager.cpp and match the wiki's error-behaviour section. They were not reproduced live.