Skip to content
Cade's Dotfiles

A Homebrew binary can't find `libX.so.N` after an upgrade

Page source

Source: Troubleshooting reference

Symptom: one program stops starting, naming a library version that used to exist:

node: error while loading shared libraries: libllhttp.so.9.3: cannot open shared object file

Root cause: brew upgrade <formula> doesn’t stop at the formula — it then rebuilds every dependent whose linkage the upgrade invalidated. Interrupt it in between (Ctrl-C, a killed terminal, a timeout) and you’re left with the new dependency and the old dependent: the dependent’s RPATH points at opt/<dep>/lib, which now holds only the new soname. Both kegs are usually still in the Cellar, so brew list looks healthy.

Confirm:

Terminal window
brew list --versions <dep>                      # e.g. llhttp 9.3.1 9.4.3
readelf -d "$(brew --prefix)/opt/<formula>/bin/<prog>" | grep RPATH

Fix: rebuild the dependent — brew upgrade <formula> (or reinstall). Don’t relink the old dependency keg; that just moves the breakage to whatever wanted the new one.

Prevention: pass HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK=1 when you upgrade something with many dependents, so nothing half-finishes in the first place.