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

Fix "module 'omarchy.workspace-layouts.1' not found" on every reload

omarchyhyprland
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

The mechanism holds. bootstrap.lua on 4.0.4-1 prepends ~/.local/state/?.lua. The shipped config/hypr/hyprland.lua template loads it with dofile. Migration 1781063758.sh rewrites the old package.path block only when its comment and first line match the old stock text exactly. omarchy-refresh-config saves .bak.$(date +%s) and prints a diff, so the danger text is accurate. Two claims are wrong. The cause says the 4.0.2 stock path list lacked the entry, but bootstrap.lua at tag v4.0.2 already adds ~/.local/state, and so does the template at v4.0.2. Issue #9664's reporter must therefore have had a pre-bootstrap or edited hyprland.lua. The symptom says none of the listed paths is under ~/.local/state, but the error quoted in #9664 starts with ~/.local/state/omarchy/toggles/hypr/.... toggles.lua prepends that directory and then requires workspace-layouts, which is consistent with the quote. The cause also says the dofile is on the template's first line, but it is on line 4 after comments. The cause and symptom were rewritten. The fix was left as it is. #9664 and its fix PR #9889 are both still open.

The cause above was rewritten on 2026-10-05 to match this note; the fix was corrected by the audit itself.
RISK

omarchy-refresh-config hypr/hyprland.lua overwrites your hyprland.lua. It saves the old one as ~/.config/hypr/hyprland.lua.bak.<epoch> and prints a diff, so copy your own lines back from that file.

Symptom

After pressing SUPER+L once, every config reload shows an error overlay: require("default.hypr.workspace-layouts"): /usr/share/omarchy/default/hypr/require_all.lua:32: module 'omarchy.workspace-layouts.1' not found: followed by a list of no file '...' paths. The list includes ~/.local/state/omarchy/toggles/hypr/..., ~/.config/... and /usr/share/omarchy/... entries, but never ~/.local/state/omarchy/workspace-layouts/1.lua.

Cause

The toggle saves ~/.local/state/omarchy/workspace-layouts/<id>.lua. /usr/share/omarchy/default/hypr/workspace-layouts.lua loads that file through require_all as the module omarchy.workspace-layouts.<id>, which resolves only when ~/.local/state/?.lua is on Lua's package.path. That entry is added by /usr/share/omarchy/default/hypr/bootstrap.lua, which the shipped ~/.config/hypr/hyprland.lua template loads with a dofile line near its top. A hyprland.lua written before the bootstrap existed has its own package.path = ... block, which lists only ~/.config and $OMARCHY_PATH. Migration 1781063758 replaces that block with the dofile line only when the block's comment and first line match the old stock text exactly. An edited file therefore keeps the old list and never gains ~/.local/state. The bootstrap has included ~/.local/state since at least 4.0.2, so a config that loads it is not affected. Issue 9664 reports the error on 4.0.2-1, and the path list in its error shows a config without the bootstrap. Both the issue and its fix PR 9889 were still open on 2026-10-05.

Fix

**Omarchy 4.** Make sure ~/.config/hypr/hyprland.lua starts by loading the bootstrap, before any require:


grep -n 'bootstrap.lua\|package.path' ~/.config/hypr/hyprland.lua

If there is no bootstrap.lua line, replace your package.path = ... block with:


-- Omarchy's bootstrap keeps path setup out of this user config.
dofile((os.getenv("OMARCHY_PATH") or "/usr/share/omarchy") .. "/default/hypr/bootstrap.lua")

Or reset the file to the shipped template and port your additions back from the backup it prints:


omarchy-refresh-config hypr/hyprland.lua

Then hyprctl reload.

Verify

hyprctl configerrors is empty after a reload, and a workspace toggled with SUPER+L keeps its layout after hyprctl reload.

Sources

workspace-layouts-module-not-found-custom-hyprland-lua