"Something went wrong during the update!" on a migration

Your update stopped part way and printed a red block ending in “Please review the output above carefully, correct the error, and retry the update.” A few lines above it there is a green Running migration (<number>) line. That number is the migration that failed. The failing script may have got part way through its own work, but the runner stops there and leaves every later migration untouched.

This page covers Omarchy 4.0.0 through 4.0.4, and notes where 3.x behaved differently.

The fix

1. Find the failing migration id. The whole update run is recorded, so read the log rather than scrolling the terminal.

   grep -n "Running migration" /tmp/omarchy-update.log | tail -5

   The last id printed is the one that stopped. /tmp/omarchy-update.log is overwritten by the next run and wiped on reboot, so read it before either.

2. See what is still queued behind it.

   omarchy-migrate --pending

   It prints one filename per pending migration. When nothing is pending it prints nothing and exits 1, so omarchy-migrate --pending; echo $? returning 1 means you are caught up. The one exception is a pre-Quattro git checkout, where it exits 1 because it cannot find the migrations directory at all (see below).

3. Re-run the migration step on its own. This is safe, and it is the normal recovery.

   omarchy-migrate

   Do not use sudo. The runner keeps its markers in ~/.local/state/omarchy/migrations/ and writes each one only after that migration exits zero, so a re-run skips everything already applied and retries the failed one from the start.

4. If it fails again, read the migration. They are short shell scripts, and the file name is the only documentation you need to find it.

   less /usr/share/omarchy/migrations/<id>.sh

   Most failures are a precondition the script assumed. Close the browser it asks you to close, install the package it expects, or make the file it edits writable, then run omarchy-migrate again.

5. Finish the update. The migration step sits in the middle of omarchy update, so the abort also skipped the AUR packages, the mise update, the orphan prune and the log check.

   omarchy update

6. Last resort, mark one migration done without running it.

   touch ~/.local/state/omarchy/migrations/<id>.sh

   Only do this after reading the script and either applying its change by hand or confirming it does not apply to your machine. Omarchy 4 has no skip flag. On 3.x the runner asked Migration <id> failed. Skip and continue? and recorded your answer under ~/.local/state/omarchy/migrations/skipped/; that prompt was removed in 4.0.

Verify it worked

omarchy-migrate --pending; echo "exit=$?"

exit=1 with no output above it is the finished state. If you want a second check, the marker count should match the shipped migration count:

ls /usr/share/omarchy/migrations/*.sh | wc -l
ls ~/.local/state/omarchy/migrations/*.sh | wc -l

Then run omarchy update once more and let it reach the restart prompt. If you were getting a “Pending Omarchy Migrations” notification at login, it should not come back on the next login. That toast comes from omarchy-migrate-notify.service, which runs once per login and offers to open omarchy-migrate in a floating terminal.

Why it happens

Migrations are small shell scripts shipped inside the omarchy package at /usr/share/omarchy/migrations/. Each is named for a Unix timestamp, and they run in that order. Their job is to bring an existing machine in line with what a new release assumes: rewrite a config file, drop a retired package, move state to a new path. A fresh install marks them all done at provisioning time, so only upgrades run them.

The state is per user. Markers live in your home, which is why a second account on the same machine sees the whole list as pending and gets the login notification the first time it signs in.

omarchy update runs them in a fixed order: prune the package cache, take a Snapper snapshot, update the keyring, update system packages, then omarchy-migrate, then the post-update hook, AUR packages, mise, and orphan removal. Migrations run after the packages because they are written against the versions that were just installed. The cost of that placement is the one people hit: a migration failure aborts the whole update and everything after it never runs.

On Omarchy 4 the runner executes each migration under bash -euo pipefail and is itself under set -euo pipefail, so a single non-zero exit ends the loop. Issue #7078 is the clearest account of the blast radius: one migration that could not run left 28 more queued behind it, and the update ended with the same generic red block. Issue #7108 describes the same shape for a migration that installs a file from the omarchy-nvim package on a machine where that package was removed.

The individual causes reported against 4.0.x are varied rather than systemic:

• A shell change, not an Omarchy bug. Migration 1787515927 failed on every Bash 5.3 machine that reached it, even with nothing to harden, because an EXIT trap ended on a false test and Bash 5.3 adopts the trap’s status as the script’s exit status, where 5.2 did not. Reported in #8832, diagnosed in #8833, fixed by PR #8835 and shipped in v4.0.2.
• Stale state that looks live. Migration 1786643346 decides a browser is open purely from SingletonLock and SingletonSocket under the profile directory. A Chromium-family browser that crashed or lost power leaves those behind, and because they sit under ~/.config rather than /tmp, rebooting does not remove them. The migration then loops forever asking you to close a browser that is not running (#6866, #7019). The stuck profile can belong to a browser you rarely open: one report had the lock in a Brave profile last used two days earlier while Chromium was the browser being closed and reopened. Moving the stale Singleton* links out of the profile, with every Chromium-family browser genuinely closed, let the migration complete immediately. The fix in PR #7026 is still unmerged as of 4.0.4.
• Running the update through sudo. In #11257 the theme handover migration looked for per-user theme state under $HOME, which sudo had set to /root, and aborted. That issue is still open and the migration is unchanged in the 4.0.4 tree.
• A pre-Quattro git checkout. omarchy-migrate defaults OMARCHY_PATH to /usr/share/omarchy, which does not exist on a legacy self-updating checkout, so --pending reports nothing while dozens are actually outstanding (#7078). See 3 to 4 Quattro.

If that did not work

If the run stops at “Waiting for pacman transaction to finish before running Omarchy migrations…”, another pacman process holds /var/lib/pacman/db.lck. The runner waits up to 15 minutes, then tells you migrations will retry at next login and exits cleanly. Let the other transaction finish rather than deleting the lock.

If you restored a Snapper snapshot at any point, treat your migration state as suspect. Markers live on the home subvolume and the changes migrations make live on the root subvolume, so a rollback rewinds the work and keeps the markers. Issue #9828 walks through one case where a boot-config migration was silently undone and never re-ran. There is no automatic detection for this; if you know which migration was reverted, delete its marker and run omarchy-migrate. See rollback with Snapper and Limine.

If the failing step was not a migration at all, the red block is the same for every part of the update. Check whether the line above it came from pacman instead: see errors occurred, no packages were upgraded and omarchy update fails or hangs.

If a config file you edited is now shadowed by a .pacnew, the migration may have succeeded while the live file stayed stale. That is covered in pacnew and pacsave files after update.

These are one-off script bugs rather than a fault in the runner, but only the Bash 5.3 one has shipped a fix. The stale-lock fix (PR #7026) and the sleep-lock no-op for legacy installs (PR #7130) were both still open pull requests when 4.0.4 shipped, so for those the workarounds above are what you have.

Related

• omarchy update fails or hangs
• Errors occurred, no packages were upgraded
• pacnew and pacsave files after update
• What migrations do
• Before you update checklist
• omarchy-migrate command reference
• Omarchy Manual: Updates