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

Finish an omarchy update that aborted partway with a red banner

omarchy
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

Log path /tmp/omarchy-update.log, the ERR trap, the red banner text, omarchy update, and omarchy debug --print -> /tmp/omarchy-debug.log all verified in bin/omarchy-update and bin/omarchy-debug. But the Cause section has the step order BACKWARDS. bin/omarchy-update runs: pkg-prune -> omarchy-snapshot create -> omarchy-update-dev -> omarchy-update-keyring -> omarchy-update-system-pkgs (packages) -> omarchy-migrate (migrations) -> hooks -> AUR. Upstream's own comment says: 'Migrations ship with the packages installed here and are written against them, so everything below waits on this finishing.' The record claims migrations run in step 2 and packages in step 3. Also: the menu is Super+Space (Super+Alt+Space is the Apps menu, per default/hypr/bindings/utilities.lua), there is no longer a git pull into ~/.local/share/omarchy (Omarchy 4 is pacman-packaged at /usr/share/omarchy), and the bare sudo pacman -Syu fallback is now BLOCKED by bin/omarchy-update-pacman-guard.

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

An aborted update leaves the system in a partial-upgrade state. Do NOT install new packages until sudo pacman -Syu completes cleanly. Installing against a half-synced database is the classic Arch way to break glibc/libalpm linkage.

Symptom

Running the update from the menu (Super + Alt + Space > Update > Omarchy) or omarchy update stops partway with a red banner: "Something went wrong during the update! Please review the output above carefully, correct the error, and retry the update." The desktop may then be in a half-updated state: theme wrong, menu items missing, or waybar/shell not restarting.

Cause

omarchy-update is a wrapper around an ordered chain, and any non-zero exit in it trips the script's trap and aborts. The real order is: pkg-prune -> omarchy-snapshot create -> omarchy-update-dev -> omarchy-update-keyring -> omarchy-update-system-pkgs (packages) -> omarchy-migrate (migrations) -> hooks -> AUR. Packages come **before** migrations, deliberately. Upstream's own comment reads 'Migrations ship with the packages installed here and are written against them, so everything below waits on this finishing.' So an abort partway leaves packages upgraded with their migrations unapplied. There is no git pull step: Omarchy 4 is pacman-packaged at /usr/share/omarchy. The whole session is teed to a log file.

Fix

Read the log first, because it is always written, even when the screen scrolled past:


less /tmp/omarchy-update.log

Understand the order so you know what state you are in. omarchy-update runs: snapshot -> keyring refresh -> **package upgrade** -> **migrations** -> post-update hooks -> AUR packages. Packages come FIRST because migrations are written against the packages they ship with. So an abort during the package step means migrations have NOT run yet (config is still old, consistent). An abort during migrations means new packages are installed against partially-migrated config.

Fix the reported cause and re-run. The update is idempotent. Already-applied migrations are tracked in ~/.local/state/omarchy/migrations and are skipped:


omarchy update

Menu equivalent: Super + Space > **Update** > **Omarchy**. (Super + Alt + Space is the Apps menu, not this.)

If the failure was in package resolution, do NOT run bare pacman -Syu, because Omarchy installs an ALPM guard that aborts direct system upgrades. Use the documented bypass for a single transaction, then resume:


sudo env OMARCHY_ALLOW_DIRECT_PACMAN=1 pacman -Syu
omarchy update

If it still fails, collect a diagnostic bundle:


omarchy debug          # writes /tmp/omarchy-debug.log, offers upload to logs.omarchy.org
omarchy debug --print  # dump to terminal instead

If the machine is unusable, reboot and pick the pre-update snapshot from the Limine menu (see limine-snapshot-rollback).

Verify

omarchy update completes and prints no error banner. tail -n 40 /tmp/omarchy-update.log shows the package transaction finishing.

Sources

omarchy-update-aborted-midway