Fix a hypr tool failing with symbol lookup error after a system update
Checked against the current Hyprland wiki and against this Omarchy 4 workstation (omarchy 4.0.2-1, hyprland 0.56.2-1, kernel 7.1.9-arch1-2). The symptom text, the do-not-symlink warning and the paru-versus-yay note are all genuinely on the FAQ page, confirmed by fetching content/faq/_index.md from hyprwm/hyprland-wiki. Three things were wrong. First, the build order list is not on the FAQ at all: the FAQ links out to the installation page, and the list lives in content/getting-started/installation.md under Manual build. The record's list matches it except that it omits the first entry, Lua, which Hyprland 0.55 and later need for the Lua config API, so the record's order was both mis-attributed and incomplete. Second, the list has grown hyprwire and hyprtoolkit, both installed here as hyprwire 0.3.1-3 and hyprtoolkit 0.5.4-4, and the record's yay -S --rebuildall line names neither. Third, the fallback recipe removes only hyprland-git, which leaves any other -git library installed to satisfy the repo package through provides=, so it does not actually end the mismatch. I confirmed the real linked set with ldd /usr/bin/Hyprland: libaquamarine.so.13, libhyprlang.so.2, libhyprutils.so.13, libhyprcursor.so.0 and libhyprgraphics.so.4, so the cause's library list was missing hyprcursor. yay --rebuildall is a real flag on yay v13.0.1 here ("Always build all AUR packages"). On the Omarchy interaction, I read /usr/share/libalpm/hooks/00-omarchy-update-guard.hook and /usr/bin/omarchy-update-pacman-guard: the guard aborts only when both -S and -u are present, so nothing in this fix trips it, and the fix contains no bare -Sy, so it is not a partial upgrade as written. The real partial-upgrade risk is installing into a system whose databases are ahead of its packages, which the corrected fix now names. Not exercised: I did not build or remove anything, so the rebuild order itself is taken from upstream rather than tested, and hyprland-git has never been installed on this machine. Also worth noting for the record's own framing, hyprlock is not installed on Omarchy 4 at all, since Omarchy locks through omarchy-shell. The applies_to list omits omarchy even though the problem is reachable there by installing -git packages, but a verdict cannot change that field.
Never symlink one .so version to another to silence the loader. Upstream is explicit that this leads to memory bugs and crashes, on both the Manual build section of the installation page and in the FAQ. Rebuild the whole stack or none of it: a half rebuilt stack is the state you are trying to leave. The separate partial-upgrade risk is in the recovery step, not the rebuild: pacman -S hyprland on a system whose sync databases are newer than its installed packages pulls in new dependencies against old ones. Upgrade fully first, with omarchy update on Omarchy, and never use a bare pacman -Sy.
Symptom
Hyprland or a hypr* tool refuses to start after a system update with <app>: symbol lookup error: <app>: undefined symbol: <symbol> or error while loading shared libraries: <lib>: cannot open shared object file: No such file or directory. Sometimes there is just an immediate crash with no message.
Cause
The hypr* stack has no stable ABI between its own libraries. Hyprland 0.56.2 links libhyprutils.so.13, libhyprlang.so.2, libhyprgraphics.so.4, libhyprcursor.so.0 and libaquamarine.so.13, each with a version in the soname, so a rebuild of any one of them can move the number or drop a symbol. If you built Hyprland yourself, or use -git AUR packages (which count as building yourself), updating one component without rebuilding the rest leaves mismatched symbols. Mixing distro packages with self-built components produces the same result, and it is the usual way this happens: a -git package declares provides= for the repo package, so pacman will happily satisfy a repo Hyprland's dependency with a git-built library. Hyprland 0.55 and later also build against Lua for the new config API, and Lua is the first entry in upstream's mandatory build order.
Fix
Rebuild the whole stack in dependency order, or stop mixing.
Order (from the Hyprland installation page, Manual build section):
Lua
hyprland-protocols
hyprwayland-scanner
hyprutils
hyprgraphics
hyprlang
hyprcursor
aquamarine
xdg-desktop-portal-hyprland
hyprwire
hyprtoolkit
hyprland
Anything else in the stack, such as hyprlock or hyprsunset, builds in any order after Hyprland.
With AUR -git packages, force a clean rebuild of every one of them rather than a plain update. hyprwire-git and hyprtoolkit-git joined the stack and are easy to miss:
yay -S --rebuildall hyprutils-git hyprlang-git hyprgraphics-git hyprcursor-git \
aquamarine-git hyprwayland-scanner-git hyprwire-git hyprtoolkit-git \
xdg-desktop-portal-hyprland-git hyprland-git
The FAQ's own wording for this case is to remove every -git hypr* package and install them again, with CleanBuild on each. It notes paru has been problematic here, so use yay, and if you do use paru, clear ~/.cache/paru of the hypr* packages by hand.
The robust fix is to drop to packaged releases entirely. Remove the whole git stack, not only hyprland-git: leaving hyprutils-git installed lets it satisfy the repo Hyprland's dependency through provides= and you are back in the same mismatch.
pacman -Qq | grep '^hypr.*-git$' # see what you actually have
yay -Rns hyprland-git hyprutils-git hyprlang-git hyprgraphics-git hyprcursor-git \
aquamarine-git hyprwayland-scanner-git hyprwire-git hyprtoolkit-git \
xdg-desktop-portal-hyprland-git
sudo pacman -S hyprland xdg-desktop-portal-hyprland
**On Omarchy 4**, run omarchy update first so the sync databases and the installed packages are at the same point, then do the pacman -S above. Installing into a system whose databases are ahead of its packages is a partial upgrade even without -Sy. Omarchy's ALPM guard does not get in the way here: /usr/bin/omarchy-update-pacman-guard aborts only when -S and -u appear in the same pacman command line, so pacman -S hyprland runs, while a bare yay (which is yay -Syu) is refused and tells you to use omarchy update. Omarchy 4 ships hyprland from extra and is built against that package, so a -git Hyprland is unsupported there regardless of whether it links.
Verify
hyprctl version # prints a version and a commit
ldd /usr/bin/Hyprland | grep 'not found' # no output
pacman -Qkk hyprland # no altered or missing files
/usr/bin/hyprland is a symlink to /usr/bin/Hyprland, so either name works with ldd.