Recover from a partial upgrade that broke shared libraries
Checked against the Arch wiki System maintenance page (partial upgrades section), the FAQ (single version of each shared library) and the Pacman page (pacman-static section), pacman's hook.c and the alpm-hooks(5) and pacman.conf(5) man pages, the AUR RPC record for pacman-static, and on this Omarchy 4 workstation the guard hook, /usr/bin/omarchy-update-pacman-guard, omarchy-update, omarchy-update-keyring, omarchy-update-system-pkgs, omarchy-pkg-add, /etc/pacman.conf and /usr/share/omarchy/install/omarchy-base.packages. What held: the cause, the -Syuw and IgnorePkg/IgnoreGroup warnings, the symlink warning, the checkupdates -d advice and the rule to finish -Su after -Sy all match the wiki wording. The pacman-static URL still answers 200 (file dated 2022-02-20) and the wiki still lists it, calling it outdated. pacman -Qkk output here is bash: 270 total files, 0 altered files, so the verify grep works. Omarchy's shipped pacman.conf sets no IgnorePkg or IgnoreGroup. What was wrong: every sudo pacman -Syu in the fix and verify is refused on Omarchy 4 by /usr/share/libalpm/hooks/00-omarchy-update-guard.hook, which aborts any pacman command line carrying both -S and -u unless OMARCHY_UPDATE_PACMAN=1 or OMARCHY_ALLOW_DIRECT_PACMAN=1 is set. omarchy-update-system-pkgs runs sudo env LC_ALL=C OMARCHY_UPDATE_PACMAN=1 pacman -Syu --noconfirm --overwrite '/usr/share/omarchy/*', so omarchy update is the Omarchy form of the wiki's recovery. The guard applies to pacman-static too, since the hook lives in the system hook directory that pacman.conf(5) says is always searched, and the guard is a bash script marked AbortOnFail (hook.c line 656 returns -1 on failure), so on a system where bash cannot start the hook itself aborts the transaction even with the bypass set. omarchy-update-keyring runs pacman -Sy archlinux-keyring right before the full upgrade, so an interrupted omarchy update produces this exact state. pacman-contrib is in Omarchy's base package list, so the pacman -S pacman-contrib line is a plain-Arch step. Sources unchanged. Not exercised: no partial upgrade was induced, the pacman-static binary was not run, and the hook-aborts-when-bash-is-broken path is read from the source, not reproduced.
Do NOT 'fix' a missing soname by symlinking libbar.so.5 -> libbar.so.6. Soname bumps mean the ABI is incompatible. The symlink will produce silent memory corruption and crashes. Also, once -Sy has run you must finish the -Su before doing any other package operation. On Omarchy 4, moving the guard hook aside removes the only thing that stops a direct pacman -Syu from bypassing omarchy update's snapshot, keyring and migration steps, so put it back as soon as the transaction is done.
Symptom
After running pacman -Sy something or pacman -S something without a full upgrade, programs start dying with things like:
foo: error while loading shared libraries: libbar.so.5: cannot open shared object file: No such file or directory
Sometimes pacman or sudo itself stops working.
Cause
Arch is a rolling release with no version pinning. pacman -Sy refreshes the sync database but installs nothing, so the next pacman -S pkg pulls in a *new* library while the rest of the system still links against the *old* soname. Partial upgrades are explicitly unsupported. pacman -Syuw and aggressive IgnorePkg/IgnoreGroup cause the same damage.
On Omarchy 4 the same rule holds, with three local details. omarchy update itself runs sudo pacman -Sy --noconfirm archlinux-keyring (in omarchy-update-keyring) immediately before pacman -Syu (in omarchy-update-system-pkgs), so an update that dies between those two steps leaves the database refreshed and nothing upgraded, which is this state. omarchy pkg add runs pacman -S --noconfirm --needed, which is safe only while the database has not been refreshed since the last full upgrade. Omarchy's shipped /etc/pacman.conf sets no IgnorePkg or IgnoreGroup, and omarchy-refresh-pacman overwrites that file, so an IgnorePkg you added is both a partial-upgrade risk and something a refresh silently removes.
Fix
Complete the upgrade you started. This is the fix, not a workaround.
**Plain Arch:**
sudo pacman -Syu
**Omarchy 4:** a direct pacman -Syu is refused by the update guard hook (/usr/share/libalpm/hooks/00-omarchy-update-guard.hook, which aborts any pacman command line carrying both -S and -u). Use the supported path, which runs pacman -Syu with the guard's own variable set:
omarchy update
or bypass the guard for one transaction:
sudo env OMARCHY_ALLOW_DIRECT_PACMAN=1 pacman -Syu
If pacman itself is broken by the missing library, use the static build. The Arch wiki calls this binary outdated (the server dates it 2022-02-20) but still points at it, because the AUR pacman-static package needs a working makepkg, which a broken system may not have:
curl -LO https://pkgbuild.com/~morganamilo/pacman-static/x86_64/bin/pacman-static
chmod +x pacman-static
sudo ./pacman-static -Syu pacman # plain Arch
sudo env OMARCHY_ALLOW_DIRECT_PACMAN=1 ./pacman-static -Syu pacman # Omarchy 4
The guard applies to pacman-static as well: hooks in /usr/share/libalpm/hooks/ run for any pacman that reads the system configuration, and the guard inspects the calling command line for -S and -u. The guard is a bash script with AbortOnFail, so if bash itself cannot start on the broken system the hook fails and pacman aborts the transaction even with the variable set. Move the hook out of the way for that one transaction:
sudo mv /usr/share/libalpm/hooks/00-omarchy-update-guard.hook /root/
sudo ./pacman-static -Syu pacman
ls /usr/share/libalpm/hooks/00-omarchy-update-guard.hook || sudo mv /root/00-omarchy-update-guard.hook /usr/share/libalpm/hooks/
The hook belongs to the omarchy package, so if the upgrade replaced that package the hook is already back and the last line does nothing.
If even pacman-static will not run, boot the Arch ISO and run its pacman with --sysroot against the mounted system (Arch wiki, Pacman, "Using an external pacman"). On Omarchy the guard hook runs inside the sysroot too, so the same variable or hook move applies.
To check for updates safely in future without touching the sync DB, use checkupdates. Omarchy 4 ships it: pacman-contrib is in its base package set and omarchy-update-available uses it. On plain Arch install it after the upgrade above has completed, not before:
sudo pacman -S --needed pacman-contrib
checkupdates # safe, does not sync the live database
checkupdates -d # pre-download pending updates to the cache
Never use pacman -Sy pkg. Always pacman -Syu or pacman -Syu pkg on plain Arch, and omarchy update then omarchy pkg add pkg on Omarchy 4. To confirm nothing is pending afterwards, use checkupdates (prints nothing when the system is current) rather than sudo pacman -Syu, which the guard refuses.
Verify
sudo pacman -Syu reports nothing to do, and the previously broken binary runs. sudo pacman -Qkk $(pacman -Qsq) | grep -v ' 0 altered files' shows no missing library files.
Sources
- https://wiki.archlinux.org/title/System_maintenance
- https://wiki.archlinux.org/title/Frequently_asked_questions
- https://wiki.archlinux.org/title/Pacman
- https://gitlab.archlinux.org/pacman/pacman/-/raw/master/lib/libalpm/hook.c
- https://pkgbuild.com/~morganamilo/pacman-static/x86_64/bin/pacman-static
- https://aur.archlinux.org/rpc/v5/info?arg[]=pacman-static