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

Read hyprctl configerrors when one ~/.config/hypr/*.lua file breaks and half the config vanishes

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

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).

  1. **Syntax error in the main hyprland.lua.** Every reload first runs luaL_loadfile on the main file only. If that fails, Hyprland records the error and keeps the old config running, so the edit just does not take.
  2. **Error inside a file loaded with require.** Hyprland replaces require with safeLuaRequire. A syntax or runtime error inside the required file is added to the error list as require("<module>"): <message>, an empty table is returned, and the caller carries on. On Omarchy 4 a typo in ~/.config/hypr/bindings.lua therefore drops that file only: your binds and your hl.unbind lines 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.
  3. **A module that cannot be found.** safeLuaRequire rethrows module '<name>' not found as a real error in the calling file. If the typo is in a require(...) line in hyprland.lua, everything below that line is skipped. On Omarchy 4 that includes require("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 found means a require line names a file that does not exist. Fix the spelling in ~/.config/hypr/hyprland.lua or create the file. Everything after that line was skipped.
  • An error with no require(...) prefix pointing at hyprland.lua itself 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.

Sources

lua-config-one-module-error-partial-load