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

Fix 'OMARCHY_PATH: unbound variable' when omarchy update runs from zsh, cron or a stripped shell

omarchyomarchy-4zshcronsystemd
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

Confirmed on 4.0.4-1: omarchy-update-dev line 7 and omarchy-channel-current line 10 read bare $OMARCHY_PATH under set -euo pipefail, omarchy-update-dev runs after omarchy-snapshot create and omarchy-update-stay-awake start, /etc/profile.d/omarchy.sh (omarchy-settings) sources env-bootstrap, and env-bootstrap is POSIX-compatible so sourcing it from ~/.zshenv works. #12858 (open, 4.0.4-1) supports the error and triggers, and a commenter reproduces it in non-login zsh. #8769 is the sibling omarchy-update-available crash. Two problems. The verify zsh -c 'echo $OMARCHY_PATH' passes without any fix inside a graphical terminal, because envs.lua sets OMARCHY_PATH with hl.env for the whole Hyprland session, so it proves nothing. And the cron/timer advice omits that an unattended update stalls anyway: omarchy-update runs inside a script pty, so omarchy-update-stay-awake sees a tty and calls sudo -v, which waits for a password nobody types unless sudo is passwordless, and -y still stops at the orphan and reboot prompts on 4.0.4-1. Fix and verify corrected. No cron or zsh run was exercised (zsh is not installed here).

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

Symptom

omarchy update takes the snapshot, then aborts:


/usr/bin/omarchy-update-dev: line 7: OMARCHY_PATH: unbound variable

Something went wrong during the update!

It works from the normal terminal but fails from a zsh started as a non-login shell, a cron job or systemd timer, an agent or editor terminal, or sudo omarchy update. Related commands fail the same way:


/usr/bin/omarchy-channel-current: line 10: OMARCHY_PATH: unbound variable

Cause

omarchy-update-dev and omarchy-channel-current run under set -euo pipefail and read $OMARCHY_PATH with no default ([[ $OMARCHY_PATH != "/usr/share/omarchy" ]] || exit 0), confirmed in the 4.0.4-1 scripts here. The variable is only exported by /usr/share/omarchy/default/bash/env-bootstrap, which is sourced from /etc/profile.d/omarchy.sh (login shells), ~/.bashrc, the uwsm session env and the bash rc chain. A non-login zsh reads none of those (/etc/zsh/zprofile is login-only), cron and env -i start empty, and sudo resets the environment, so the variable is unset and set -u kills the update after the snapshot is already taken.

Fix

Run the update through a bash login shell, as your own user, never through sudo:


bash -lc 'omarchy update'

If zsh is your shell, make every zsh pick up the Omarchy environment by adding this to ~/.zshenv (read by login and non-login zsh alike):


[ -r /usr/share/omarchy/default/bash/env-bootstrap ] &&
  . /usr/share/omarchy/default/bash/env-bootstrap

For a cron job or systemd user timer, bash -lc 'omarchy update -y' or Environment=OMARCHY_PATH=/usr/share/omarchy in the unit clears this error, but on 4.0.4-1 that alone does not make an unattended update work. omarchy-update runs inside a pty opened by script, so its sleep-inhibitor step sees a terminal and calls sudo -v, and paccache, snapper and pacman also run through sudo. Without passwordless sudo the run waits at a password prompt nobody can answer. -y also still stops at the orphan and reboot prompts on 4.0.4-1. Run updates from a terminal unless you have arranged both.

Verify

env -u OMARCHY_PATH zsh -c 'echo $OMARCHY_PATH' prints /usr/share/omarchy (the env -u matters, because a terminal inside the Hyprland session already inherits the variable), and omarchy update gets past Create system snapshot without the unbound-variable line.

Sources

omarchy-path-unbound-variable-zsh-cron