Introduction

When a shared library is installed or updated on Linux, the dynamic linker (ld.so) uses a cache file (/etc/ld.so.cache) to locate libraries quickly. This cache is built by ldconfig. If ldconfig is not run after installing a new library, the linker cannot find it, causing applications to fail with cannot open shared object file: No such file or directory even though the library file exists on disk.

Symptoms

  • Application fails with error while loading shared libraries: libfoo.so.1: cannot open shared object file
  • ldd /usr/bin/myapp shows libfoo.so.1 => not found
  • Library file exists at /usr/local/lib/libfoo.so.1 but is not found
  • ldconfig -p | grep libfoo returns nothing
  • After running ldconfig, the same application works correctly

Common Causes

  • ldconfig not run after make install of a manually compiled library
  • Library installed to non-standard path not in /etc/ld.so.conf.d/
  • Custom library path /opt/myapp/lib not configured in ldconfig
  • ldconfig cache corrupted or /etc/ld.so.cache deleted
  • Library symlink missing or broken (libfoo.so -> libfoo.so.1)

Step-by-Step Fix

  1. 1.Verify the library file exists:
  2. 2.```bash
  3. 3.find / -name "libfoo.so*" 2>/dev/null
  4. 4.ls -la /usr/local/lib/libfoo.so*
  5. 5.`
  6. 6.Check current ldconfig cache:
  7. 7.```bash
  8. 8.ldconfig -p | grep libfoo
  9. 9.# If nothing returned, the cache does not know about this library
  10. 10.`
  11. 11.Run ldconfig to rebuild the cache:
  12. 12.```bash
  13. 13.sudo ldconfig
  14. 14.# Verify
  15. 15.ldconfig -p | grep libfoo
  16. 16.`
  17. 17.Add custom library paths to ldconfig configuration:
  18. 18.```bash
  19. 19.echo "/usr/local/lib" | sudo tee /etc/ld.so.conf.d/local.conf
  20. 20.echo "/opt/myapp/lib" | sudo tee /etc/ld.so.conf.d/myapp.conf
  21. 21.sudo ldconfig
  22. 22.`
  23. 23.Fix broken library symlinks:
  24. 24.```bash
  25. 25.cd /usr/local/lib
  26. 26.ls -la libfoo.so*
  27. 27.# If libfoo.so symlink is missing:
  28. 28.sudo ln -sf libfoo.so.1.2.3 libfoo.so
  29. 29.sudo ldconfig
  30. 30.`
  31. 31.Debug with LD_LIBRARY_PATH as a temporary workaround:
  32. 32.```bash
  33. 33.export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
  34. 34.ldd /usr/bin/myapp
  35. 35../myapp
  36. 36.`

Prevention

  • Always run sudo ldconfig after make install of libraries
  • Add post-install hooks in packaging scripts: post_install: ldconfig
  • Use ldconfig -v to verbose-check all library paths during deployment
  • Verify library resolution with ldd as part of application deployment validation
  • Configure all non-standard library paths in /etc/ld.so.conf.d/ at installation time