Theme half-applied after a failed update: 'omarchy theme current' says Unknown and the wallpaper symlink dangles
Re-read /usr/share/omarchy/bin/omarchy-theme-set, omarchy-theme-current, omarchy-theme-bg-current, omarchy-theme-refresh, omarchy-theme-remove, omarchy-theme-set-templates, omarchy-theme-set-browser, omarchy-theme-set-browser-policy and omarchy-reinstall-configs on this workstation at omarchy 4.0.2-1, and re-read omacom/omarchy issues 7116 and 8262 in full. Most of the first-pass note holds on 4.0.2-1: the interrupted-swap window is still the two adjacent lines rm -rf "$CURRENT_THEME_PATH" then mv "$NEXT_THEME_PATH" "$CURRENT_THEME_PATH" with theme.name written afterwards, the three paths are correct, the no-backgrounds branch really notifies and returns without touching the link, INSTALLED_THEME_DENIED=(alacritty.toml foot.ini ghostty.conf kitty.conf vscode.json) and both stderr lines are verbatim, and the colors.toml gate is real (if [[ -f $COLORS_FILE ]] wraps the whole template loop). Confirmed on this machine that all 22 shipped themes ship a backgrounds/ directory, so step 2's claim that any shipped theme rebuilds everything holds for shipped themes only. Five defects. First, the record contradicts itself: omarchy-theme-current prints Unknown only when ~/.local/state/omarchy/current/theme.name is absent, and the rm -rf deletes current/theme, not current/theme.name, so an interrupted swap leaves theme.name holding the **previous** name and omarchy theme current prints that. Unknown is a different and rarer state. Second, and following from it, omarchy-theme-refresh is a no-op in exactly the state the symptom describes: it is if [[ -f $THEME_NAME_PATH ]]; then OMARCHY_THEME_SKIP_BACKGROUND=1 omarchy-theme-set "$(cat $THEME_NAME_PATH)"; fi, so with theme.name missing it exits 0 and changes nothing, and it is not a lighter operation than a set because it re-runs the same rm -rf of current/theme. Third, the record's own step 2 is the trap the danger should have named: a bare rm -rf .../current/next-theme while a theme change is actually running, which is what an interrupted omarchy update means, deletes the staging directory out from under it, and the subsequent mv then fails after current/theme has already been removed, leaving you worse off than you started. Fourth, omarchy-theme-set-browser at step 6 hangs: refresh_running_browser runs "$command" --refresh-platform-policy --no-startup-window &>/dev/null in the **foreground** with no timeout (&> is a redirect, not a background), and it first calls omarchy-theme-set-browser-policy, which re-execs itself privileged. Fifth, the cause lists icons.theme among files rendered from default/themed/*.tpl, and there is no icons.theme.tpl: /usr/share/omarchy/themes/gruvbox/icons.theme is shipped by the theme and copied at staging. The first auditor spotted this and left it. Also new on 4.0.2-1 and unmentioned: theme changes serialise on flock at ${XDG_RUNTIME_DIR:-/tmp}/omarchy-theme-set.lock, released before the app retint hooks. Source 8262 is being removed: it resolves, but its title and body are about the theme switcher menu never rendering a layer surface and the menu action failing to invoke omarchy-theme-set, which is a shell IPC problem and supports no claim in this record. NOT exercised: no theme command was run, nothing was deleted, no browser was refreshed, and /etc/sudoers.d/ is unreadable unprivileged so I could not confirm from here whether the browser policy helper's privilege escalation is passwordless or prompts.
**Do not rm -rf the staging directory while a theme change is running.** That is how a bad state becomes a worse one: omarchy-theme-set deletes current/theme and then mvs next-theme into its place, so removing next-theme under a live swap makes the mv fail after current/theme is already gone, and you lose the theme you still had. Run pgrep -a -f omarchy-theme-set first, and never do this while an omarchy update is still in progress.
Never rm -rf ~/.local/state/omarchy/current while the shell is running. Delete only next-theme, and re-apply with omarchy theme set.
**Do not run omarchy-theme-set-browser by hand to retint a browser.** It calls a privileged helper that writes the enterprise policy directories under /etc, and it then runs brave --refresh-platform-policy --no-startup-window in the foreground with no timeout, so on some machines it simply never returns and your terminal sits there. Let omarchy theme set run it as one of its own parallel hooks, and if a browser did not retint, restart the browser instead.
Reach for omarchy-reinstall-configs only as a last resort: it replays /etc/skel over your entire $HOME (cp -af /etc/skel/. ~/) and overwrites every Omarchy-shipped user config, including your ~/.config/hypr/*.lua overrides, with no backup.
omarchy theme remove is an unconditional rm -rf of ~/.config/omarchy/themes/<name>. Commit any local edits to that theme first.
Symptom
After an interrupted omarchy update or a theme switch that died partway, the desktop is visually inconsistent: terminal, bar and GTK apps disagree on colors, window borders are the wrong accent, the wallpaper is missing or reverts to the default.
The common shape. theme.name is written only after the swap completes, so it still holds the **previous** theme and the staged theme directory is simply gone:
$ omarchy theme current
Gruvbox # the theme you were on, not the one you asked for
$ ls ~/.local/state/omarchy/current/theme
ls: cannot access '...': No such file or directory
$ readlink ~/.local/state/omarchy/current/background
/home/you/.local/state/omarchy/current/theme/backgrounds/1-quattro.jpg
$ readlink -f ~/.local/state/omarchy/current/background
# resolves to nothing - dangling
The rarer shape, where theme.name itself is gone, usually because someone deleted current/:
$ omarchy theme current
Unknown
$ omarchy theme bg current
Unknown
The two matter because omarchy-theme-refresh works in the first and silently does nothing in the second.
A git-installed theme can also produce "my theme's terminal colors and window borders are wrong", with this on stderr from the theme set:
Ignored in /home/you/.config/omarchy/themes/foo: hyprland.lua alacritty.toml
A theme installed from a git repo cannot supply Lua, a terminal config, or vscode.json.
Cause
omarchy-theme-set stages into ~/.local/state/omarchy/current/next-theme, then swaps:
rm -rf "$CURRENT_THEME_PATH"
mv "$NEXT_THEME_PATH" "$CURRENT_THEME_PATH"
echo "$THEME_NAME" >"$HOME/.local/state/omarchy/current/theme.name"
Interrupted between the first two lines, current/theme is gone while current/background still points inside it, which is the dangling symlink, and theme.name was never updated so it still names the theme you were on. The same end state is reached deliberately when a theme ships no backgrounds/ directory: the notification says "No background was found for theme" and returns without touching current/background, but the previous wallpaper lived inside the directory that was just deleted (issue #7116). All 22 shipped themes do ship backgrounds, so that branch only bites on a user or git-installed theme. Note the path moved in Omarchy 4: the live theme state is ~/.local/state/omarchy/current/, not ~/.config/omarchy/current/.
omarchy-theme-current prints Unknown only when theme.name is absent, and omarchy-theme-bg-current prints Unknown because readlink -f on a dangling link yields nothing. Those are two different failures and the recoveries differ.
Per-app files (btop.theme, shell.toml, hyprland.lua, chromium.theme, helix.toml, neovim.lua, pi.json…) are rendered from /usr/share/omarchy/default/themed/*.tpl **only when the staged theme has a colors.toml**, so a theme without one leaves those files stale. icons.theme is not one of them: there is no icons.theme.tpl, and the file is shipped by the theme itself and copied at staging. A template of the same name under ~/.config/omarchy/themed/ overrides the shipped one, so a broken user template silently produces a broken generated file.
A theme cloned by omarchy theme install <git-url> has every *.lua, alacritty.toml, foot.ini, ghostty.conf, kitty.conf and vscode.json dropped at staging time on purpose, because those name a program to run, with the generated template used instead, so it can legitimately look different from the author's screenshots.
Theme changes serialise on a lock at ${XDG_RUNTIME_DIR:-/tmp}/omarchy-theme-set.lock, held across the staging and swap and released before the app retint hooks. A second theme change issued during a swap waits rather than racing it.
Fix
# 1. Make sure nothing is mid-swap before you touch anything. An interrupted
# `omarchy update` may still be running one.
pgrep -a -f omarchy-theme-set
# 2. See what state it is actually in
ls -l ~/.local/state/omarchy/current/
cat ~/.local/state/omarchy/current/theme.name # absent = the rarer shape
readlink -f ~/.local/state/omarchy/current/background # empty output = dangling
ls ~/.local/state/omarchy/current/theme/ # colors.toml + generated files
# 3. Only once step 1 printed nothing, clear any half-written staging
# directory and re-apply cleanly. omarchy-theme-set removes next-theme
# itself, so this is only for the case where it died holding one.
rm -rf ~/.local/state/omarchy/current/next-theme
omarchy theme list
omarchy theme set "Tokyo Night" # any SHIPPED theme rebuilds everything,
# including the background link
# 4. Already on the theme you want, per `omarchy theme current`, and only the
# per-app files are stale. This re-runs the full set minus the background,
# and does nothing at all if theme.name is missing.
omarchy-theme-refresh
# 5. Wallpaper only
omarchy theme bg next
omarchy theme bg current
# 6. Half-installed or broken third-party theme
omarchy theme remove <name>
omarchy theme install https://github.com/author/omarchy-<name>-theme.git
# 7. Apps that did not retint. omarchy-theme-set runs these in parallel itself,
# so reach for them only when one of them is the thing that failed.
omarchy-restart-terminal
omarchy-restart-hyprctl # window borders / gradients
omarchy-restart-btop
omarchy-theme-set-gnome # GTK apps
If a shipped theme still will not render its per-app files, check that colors.toml reached the staged theme, and that no broken user template is overriding a shipped one. Without colors.toml no template runs at all:
ls -l ~/.local/state/omarchy/current/theme/colors.toml
ls -l ~/.config/omarchy/themed/*.tpl 2>/dev/null
Verify
omarchy theme current prints the theme you asked for. readlink -f ~/.local/state/omarchy/current/background resolves to a real image file. ls ~/.local/state/omarchy/current/theme contains colors.toml plus the generated shell.toml, btop.theme and hyprland.lua. pgrep -f omarchy-theme-set prints nothing, so the swap finished.
Sources
- https://raw.githubusercontent.com/basecamp/omarchy/quattro/bin/omarchy-theme-set
- https://raw.githubusercontent.com/basecamp/omarchy/quattro/bin/omarchy-theme-refresh
- https://raw.githubusercontent.com/basecamp/omarchy/quattro/bin/omarchy-theme-list
- https://raw.githubusercontent.com/basecamp/omarchy/quattro/bin/omarchy-theme-remove
- https://raw.githubusercontent.com/basecamp/omarchy/quattro/bin/omarchy-reinstall-configs
- https://raw.githubusercontent.com/basecamp/omarchy/quattro/docs/theming.md
- https://github.com/basecamp/omarchy/issues/7116
- https://raw.githubusercontent.com/omacom/omarchy/quattro/bin/omarchy-theme-set
- https://raw.githubusercontent.com/omacom/omarchy/quattro/bin/omarchy-theme-set-templates
- https://raw.githubusercontent.com/omacom/omarchy/quattro/bin/omarchy-theme-refresh
- https://raw.githubusercontent.com/omacom/omarchy/quattro/bin/omarchy-theme-current
- https://raw.githubusercontent.com/omacom/omarchy/quattro/bin/omarchy-theme-set-browser
- https://github.com/omacom/omarchy/issues/7116