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

$mainMod and source= have no direct Lua equivalent after the 0.55 migration

hyprlandomarchyarchendeavouroscachyosmanjarowayland
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

Most of this is solid and matches the Start Here page: require() gives each file its own Lua scope so an error in one does not stop the others. A MISSING module is the documented exception ("require(\"nonexistent\") in your main Hyprland config will kill the execution of your main config") and pcall is the wiki's own remedy. . and / are both valid separators. Wildcards are supported. hyprlang $var really has no Lua equivalent so locals + a module returning a table is the right port. The Omarchy 4 ordering block is verbatim correct: quattro's config/hypr/hyprland.lua opens with dofile((os.getenv("OMARCHY_PATH") or "/usr/share/omarchy") .. "/default/hypr/bootstrap.lua"), then require("default.hypr.omarchy"), then hypr.monitors / hypr.input / hypr.bindings / hypr.looknfeel / hypr.autostart (the real file also ends with require("default.hypr.toggles")), so o.* being nil in a carried-over Omarchy 3 config is a genuine failure mode. The defect is the absolute-path claim: the wiki explicitly documents require("/usr/share/among/us.lua") alongside require("./stuff/*"), i.e. require DOES take absolute paths and DOES accept a .lua extension there. What it does not do is expand ~. The record generalizes the tilde bug into a false rule about absoluteness and prints it as the reason to reach for loadfile.

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

A syntax error early in hyprland.lua means no binds get registered at all. Hyprland catches this and gives you emergency binds (SUPER+Q terminal, SUPER+R run, SUPER+M exit), but if you have rebound SUPER or run a non-standard terminal you can end up in a session you cannot drive. Before a big migration, confirm you can reach a TTY with Ctrl+Alt+F2, and test with Hyprland --verify-config rather than by logging out.

Symptom

Half-migrated config throws errors on reload: attempt to index a nil value (global 'o'), attempt to call a nil value, attempt to concatenate a nil value (global 'mainMod'), or module 'modules.monitors' not found. Symptoms in the session: whole blocks of keybinds silently missing, the Hyprland emergency-binds banner, or one file's worth of settings gone while the rest applied. Requiring an absolute path produces a mangled result like /home/you//~/.config/wal/colors-hyprland.lua.

Cause

hyprlang's $name = value was text substitution and source = ./other.conf was a textual include. Lua has neither. $mainMod becomes an ordinary Lua local and obeys Lua scope: a local in hyprland.lua is NOT visible inside a file you require(), because Hyprland deliberately gives each required file its own scope so an error in one does not kill the others. source = becomes require(), which resolves module names against package.path relative to hyprland.lua, accepts . or / as the separator, and supports wildcards. require also accepts ABSOLUTE paths (the wiki's own example is require("/usr/share/among/us.lua"), extension included), so absoluteness is not the problem. The problem is that ~ is never expanded, so require("~/.cache/wal/colors-hyprland") gets glued onto the config directory and yields a path like /home/you//~/.cache/.... And a missing module is one of the few errors require()'s protection does not cover: require("nonexistent") throws in the calling file and kills the rest of it.

Fix

Same as written, except the absolute-path section. Absolute paths work fine with require. It is ~ that does not expand:


-- WRONG: ~ is never expanded -> /home/you//~/.cache/...
-- require("~/.cache/wal/colors-hyprland")

-- Fine: require takes an absolute path, extension included
require(os.getenv("HOME") .. "/.cache/wal/colors-hyprland.lua")

For a generated file that may not exist yet (pywal, theme output), still prefer loadfile, not because the path is absolute, but because loadfile returns nil instead of throwing and so cannot take the rest of the file down with it:


local chunk = loadfile(os.getenv("HOME") .. "/.cache/wal/colors-hyprland.lua")
if chunk then chunk() end

Everything else in the record stands: locals + a module that returns a table for shared variables, require("monitors") / require("modules.binds") / require("./themes/*") for includes, pcall(require, "maybe-missing") for optional ones, the Omarchy bootstrap ordering, and hyprctl reload && hyprctl configerrors / hyprctl binds to confirm.

Verify

hyprctl configerrors is empty, hyprctl binds lists binds originating from every required file, and Hyprland --verify-config exits 0.

Sources

hyprlang-variables-and-source-to-lua