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

Recover from a custom theme that leaves the terminal unable to start

omarchyomarchy-4hyprlandwayland
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

Checked on this workstation at omarchy 4.0.2-1, omarchy-settings 4.0.2-1, foot 1.27.0-2, with alacritty, kitty and ghostty not installed. The core mechanism holds exactly: /usr/share/omarchy/bin/omarchy-theme-set-templates:371 is if [[ -f $COLORS_FILE ]], /usr/share/omarchy/config/foot/foot.ini:2 is an unconditional include, alacritty and kitty include unconditionally and only ghostty uses the guarded config-file = ?"..." form, omarchy-restart-terminal has no foot action so open windows survive, default/xdg-terminal-exec names only foot.desktop, and all 22 directories under /usr/share/omarchy/themes ship a colors.toml. I reproduced the symptom text exactly: foot --check-config against a config whose include is missing prints err: config.c:896: ... failed to open: No such file or directory and exits 230. Four things are wrong. First and worst, the fix does not work: I ran omarchy-theme-set-templates in a sandboxed HOME against the record's own three-key colors.toml and omarchy-theme-color --all returns empty strings for red, green, yellow, blue, magenta and cyan, so the generated foot.ini carries regular1= with no value and foot still refuses, now with err: config.c:3268: [colors-dark].regular1: syntax error: key/value pair has no value and exit 230. Repeating the same sandbox with the six hues added gave a foot.ini that foot --check-config accepts with exit 0, so the corrected fix carries nine keys and points at a shipped palette as the easier route. Second, the recovery path assumed a terminal or a TTY and missed the terminal-free one: default/hypr/bindings/utilities.lua:18 binds SUPER + SHIFT + CTRL + SPACE to omarchy-menu toggle theme, and default/omarchy/omarchy-menu.jsonc key style.theme runs omarchy-theme-switcher then omarchy-theme-set. Third, the cause and danger claim omarchy theme install applies a repo with no validation, which was true at the commit in issue 7105 but is false on 4.0.2: omarchy-theme-install calls omarchy-git-url-check, holds the theme name to ^[a-z0-9_][a-z0-9._+-]*$, and omarchy-theme-set stages a cloned theme through stage_installed_theme, refusing symlinks at any depth and dropping INSTALLED_THEME_DENIED=(alacritty.toml foot.ini ghostty.conf kitty.conf vscode.json) plus every .lua, naming them on stderr. That change makes the failure stricter for the clone path, because a cloned theme can no longer ship its own foot.ini to cover the gap. Fourth, the verify field's hyprland.conf is Omarchy 3 wording taken from the issue's own reproduction. Omarchy 4 generates hyprland.lua from default/themed/hyprland.lua.tpl, and my sandbox run produced 18 files including shell.toml and hyprland.lua. I dropped severity from high to medium because the blast radius is narrower than the record implies: the theme's hyprland.lua and gum_env.lua are loaded with require_optional (default/hypr/omarchy.lua:22, default/hypr/envs.lua:5), so a missing one does not break the Hyprland session, open terminals keep running, and recovery is one keybinding away with no terminal at all. Issue 7105 is open on omacom/omarchy, I read it in full, and it supports the record including its own appended correction that only new foot launches break. The cited omacom manual page returns 200 and does say colors.toml is the file to tweak, but its app list is Omarchy 3 era (Hyprlock, Mako, SwayOSD, Walker, Waybar) and it never mentions foot, so it backs the palette claim only. NOT exercised: I did not install a theme, run omarchy-theme-set, or change the live theme on this machine, so every claim about the applied result comes from reading the scripts plus the sandboxed template run under a throwaway HOME. I also did not test whether Ctrl+Alt+F2 reaches a getty on this install.

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

omarchy theme install <git-url> clones a repository into ~/.config/omarchy/themes/ and applies it immediately. On Omarchy 4.0.2 the URL is checked by omarchy-git-url-check, the theme name is held to ^[a-z0-9_][a-z0-9._+-]*$, symlinks are refused at any depth, and alacritty.toml, foot.ini, ghostty.conf, kitty.conf, vscode.json and every .lua are dropped and named on stderr, so a cloned theme cannot run code at login. Nothing checks that the theme has a colors.toml, so a repo you have not read can still leave you unable to open a new terminal. Look at the repo before installing it.

Symptom

After omarchy theme install <git-url> or omarchy theme set <my-theme>, new terminal windows refuse to open. Running foot by hand prints: err: config.c:896: /home/<user>/.config/foot/foot.ini:2: [main].include: ~/.local/state/omarchy/current/theme/foot.ini: failed to open: No such file or directory and exits 230. omarchy theme set itself exited 0 with no warning.

Cause

bin/omarchy-theme-set applies any directory under ~/.config/omarchy/themes/ whose name passes its regex, and the template generator only runs if [[ -f $COLORS_FILE ]] (/usr/share/omarchy/bin/omarchy-theme-set-templates:371). A theme with no colors.toml, and no legacy alacritty.toml to convert from, therefore produces a ~/.local/state/omarchy/current/theme/ with none of the generated files: no foot.ini, alacritty.toml, kitty.conf, ghostty.conf, shell.toml or hyprland.lua. /usr/share/omarchy/config/foot/foot.ini:2 is an unconditional include of that missing foot.ini and foot treats a missing include as fatal. Alacritty (general.import) and kitty (include) are unconditional too, and only Ghostty is guarded, with config-file = ?"...". The Hyprland session is not affected, because the theme's hyprland.lua and gum_env.lua are loaded through require_optional (default/hypr/omarchy.lua:22, default/hypr/envs.lua:5), and already-open terminal windows keep running because omarchy-restart-terminal has no foot action. You only discover it when you open a new window, and omarchy theme set exited 0 with no warning. On Omarchy 4.0.2 a theme installed from a git repo is staged rather than copied wholesale, and foot.ini is on the refused list, so such a theme cannot ship its own foot.ini to cover the gap. Only a colors.toml closes it.

Fix

You do not need a terminal to get out of this. Press **Super+Shift+Ctrl+Space** for the Theme menu, or **Super+Space** and pick Style then Theme, then choose a stock theme. That menu entry runs omarchy-theme-switcher and omarchy-theme-set directly, so it works with every terminal on the machine broken.

If a terminal window is still open it keeps working, so you can switch back there instead:


omarchy theme set tokyo-night

If the graphical session is gone as well, get a shell from a TTY with Ctrl+Alt+F2, log in, and run the same command.

To keep the broken theme, give it a colors.toml. A three-key file is not enough: omarchy-theme-color returns an empty string for every hue it cannot derive, so the generated foot.ini gets regular1= with no value and foot still refuses to start, this time with err: config.c:3268: [colors-dark].regular1: syntax error: key/value pair has no value and exit 230. The smallest file that produces a config foot accepts carries the six hues too:


cat > ~/.config/omarchy/themes/<my-theme>/colors.toml <<'EOF'
mode       = "dark"
background = "#1a1b26"
foreground = "#c0caf5"
red        = "#f7768e"
green      = "#9ece6a"
yellow     = "#e0af68"
blue       = "#7aa2f7"
magenta    = "#ad8ee6"
cyan       = "#449dab"
EOF
omarchy theme set <my-theme>

Copying a shipped palette and editing the values is easier and fills in every optional key, including the bright and background shades the templates otherwise derive:


cp /usr/share/omarchy/themes/tokyo-night/colors.toml ~/.config/omarchy/themes/<my-theme>/colors.toml
omarchy theme set <my-theme>

Before installing any third-party theme, check it first:


ls ~/.config/omarchy/themes/<name>/colors.toml || echo "NO colors.toml - new terminal windows will not open"

Verify

foot --check-config; echo $? returns 0, and ls -A ~/.local/state/omarchy/current/theme lists the generated files as well as whatever the theme shipped: colors.toml, foot.ini, alacritty.toml, kitty.conf, ghostty.conf, shell.toml and hyprland.lua are all present. If the directory holds only the theme's own images, icons.theme and similar, the template pass did not run.

Sources

installed-theme-without-colors-toml-breaks-foot