omarchy update fails or hangs part way through

An Omarchy update that stops part way is almost always recoverable. The update is a pipeline of small scripts, and the transcript tells you which one died. Start there before you reboot or roll back.

The fix

1. Read the transcript. omarchy update re-executes itself under script(1), so the whole session lands in /tmp/omarchy-update.log. Open it with less -R /tmp/omarchy-update.log and jump to the end. Each stage prints a green heading (Update system packages, Update Arch signing keys, Running migration (...)), so the last heading is the stage that failed. The log lives in /tmp, so copy it somewhere before you reboot.

2. Run the built-in check: omarchy-update-analyze-logs. On 4.0.4 it scans that same log for one high-value condition, a failed initramfs rebuild, and prints Error: Initramfs generation may have failed. Review logs before restart. If you see that, do not reboot yet. Fix the initramfs first, or roll back.

3. If it hung instead of failing, find the child process before you kill anything:

   pstree -aps $(pgrep -f 'omarchy-update' | head -1)

   A hang under omarchy-hook post-update or under a migration calling omarchy-theme-set points at a custom or plugin-installed hook. Move ~/.config/omarchy/hooks/ aside and retry.

4. Rerun the update. omarchy update is safe to repeat: pacman either committed the transaction or did not, and omarchy-migrate records each finished migration as a marker file under ~/.local/state/omarchy/migrations/, so completed migrations are skipped.

5. If you get An Omarchy update is already running., a real process still holds a flock on $XDG_RUNTIME_DIR/omarchy-update.lock. Find it with pgrep -af omarchy-update and end it. The lock is held on an open file descriptor, so it releases the moment the process is gone. The file itself stays on disk and is harmless; deleting it does not unblock anything.

6. If the log ends in You need at least 10 GiB free to safely update Omarchy., free space on / and retry. sudo paccache -rk1 and pruning Snapper snapshots are the usual wins. The update’s own cache prune (paccache -rk2) runs after this check, so it cannot rescue you here. OMARCHY_UPDATE_FORCE=1 omarchy update bypasses the check, which is a bad idea mid-kernel-upgrade.

7. If the log ends in error: unresolvable package conflicts detected, run the update interactively, without -y. Omarchy reruns pacman without --noconfirm in that case so you can answer the replace question yourself, and it refuses to do so under -y or without a terminal.

8. If a single migration failed, fix the cause and run omarchy-migrate on its own. A migration only gets its marker after it succeeds, so the failed one is still pending and runs again; the ones that finished are skipped. omarchy-migrate --pending lists what is still outstanding. To force a migration that already completed to run again, remove its marker first:

   rm ~/.local/state/omarchy/migrations/<migration>.sh
   omarchy-migrate

9. If the machine will not boot, or the failure hit the kernel or bootloader, pick the pre-update snapshot in the Limine menu instead. See /upgrade/rollback-with-snapper-and-limine/.

Verify it worked

Run omarchy update once more. A clean run ends with the restart prompt and no red trap message. Then confirm nothing is left pending:

omarchy-migrate --pending   # prints nothing and exits non-zero when clean
pacman -Qu                  # no pending upgrades
omarchy-version

If omarchy-update-analyze-logs is quiet after a fresh run, either the initramfs rebuilt or no kernel package was touched. The check only fires when the log contains an Updating linux initcpios line without a matching success line.

Why it happens

On 4.x the update is package-backed. omarchy-update takes a lock, checks for 10 GiB free, prunes the package cache, takes a Snapper snapshot, updates the keyrings, runs pacman -Syu, then runs migrations, post-update hooks, AUR and mise updates, and the log analyzer. Any step that exits non-zero trips a shell trap that prints Something went wrong during the update! followed by Please review the output above carefully, correct the error, and retry the update. That message is generic on purpose. The real cause is in the lines above it.

Four causes account for most reports we could verify:

• A hook that is not a bash script. omarchy-hook runs every file in a hook directory with bash, ignoring the shebang and the executable bit. A Python hook gets half-interpreted, and a line starting with import runs ImageMagick’s import, which waits forever for a click. Reported independently in #8492, #9294 and #9845, all still open as of 4.0.4. A plugin can install such a hook without you knowing.

• A migration that hits an environment it did not expect. Migration 1787515927 failed for users on Bash 5.3 (#8832); ryanrhughes fixed it in PR #8835, and the 4.0.2 release notes list a fix for migration failures on Bash 5.3.

• Unowned files pacman refuses to overwrite. Omarchy clears leftovers it recognises as its own, but files outside that set stop the transaction. In #9142 a kernel downgrade plus kernel-modules-hook left the running kernel’s module tree owned by nobody, and every later update failed with 6,454 exists in filesystem lines. PR #9285 proposes handling it and is still open. Rebooting into the installed kernel first, then updating, clears it.

• A DKMS module that fails to build. In #12044 the 4.0.4 kernel migration reported module not found: 'nvidia', but a commenter showed the real failure was the NVIDIA DKMS build being killed by the OOM killer during a parallel compile. The initramfs error is downstream of that.

3.x differs. On 3.8.4 and earlier the update was a git pull into ~/.local/share/omarchy plus omarchy-update-perform. There was no update lock, no free-space check and no package cache prune, and a failed snapshot aborted the update instead of warning and carrying on. /tmp/omarchy-update.log and omarchy-update-analyze-logs already existed, so step 1 and step 2 work on 3.x too.

If that did not work

Collect the evidence rather than guessing. omarchy-debug writes a diagnostic dump to /tmp/omarchy-debug.log (--print sends it to the terminal instead), and omarchy-upload-log this-boot pushes the current boot journal to logs.omarchy.org with a 24 hour expiry so you can paste one URL into an issue or the Discord. Include the last green stage heading from /tmp/omarchy-update.log.

If the update keeps failing at the same package transaction, check whether your real problem is a mirror or signature issue rather than the updater. See /fix/failed-to-retrieve-some-files-pacman/ and /fix/signature-is-unknown-trust-keyring/.

As a last resort the manual points at omarchy reinstall, which reinstalls the default packages, puts you back on stable and resets the Omarchy config files. It overwrites your customisations of those defaults, so back up ~/.config/hypr/ and ~/.config/omarchy/ first.

Related

• /fix/migration-failed-mid-update/
• /fix/creating-a-snapshot-failed-snapper/
• /fix/errors-occurred-no-packages-were-upgraded/
• /fix/plugin-fails-to-load/
• /upgrade/before-you-update-checklist/
• /upgrade/what-migrations-do/
• /reference/commands/omarchy-update/
• /releases/still-broken/