"Error While Loading Shared Libraries: Cannot Open Shared Object File"

The binary wants a library the loader can't find: missing package, wrong arch, or a non-standard install dir that needs ldconfig. ldd turns guesswork into a named list.

What you'll see

Root causes

Library genuinely missing (or wrong version)

ldd <binary> 2>&1 | grep 'not found' names the exact unmet dependency. Then find the package that owns it: apt-file find / dnf provides / pacman -F.

Library exists but not in the loader cache

Manually installed libs (e.g. /opt/... or /usr/local/lib) aren't in /etc/ld.so.cache. Add the dir to /etc/ld.so.conf.d/ and run ldconfig — LD_LIBRARY_PATH is the quick-and-dirty alternative.

Architecture/ABI mismatch (x86_64 vs aarch64, musl vs glibc)

Alpine-built containers running Debian binaries (or vice versa) fail exactly this way: the 'missing' file exists but is the wrong ELF class. file /usr/lib/<...> shows the arch.

Fix it

  1. List the unresolved dependency by name
    ldd <binary> 2>&1 | grep -i 'not found'
  2. Install the package that ships it
    apt install libssl-dev 2>/dev/null || apt-file find libssl.so.3 ; # rhel: dnf provides '*/libssl.so.3'
  3. Non-standard paths: register with ldconfig
    echo /opt/myapp/lib | sudo tee /etc/ld.so.conf.d/myapp.conf && sudo ldconfig
  4. Arch mismatch: use the matching base image or build natively
    dpkg --print-architecture ; file <binary>   # ELF x86-64 binary on aarch64 host = rebuild with the right -march/platform image

Field note

LD_LIBRARY_PATH works but is order-sensitive and fragile across shells/contexts — ld.so.conf.d is the durable fix. Static builds (or vendoring libs in the image) kill this entire class of error for shipped tooling.

Common questions

Why does it work with LD_LIBRARY_PATH but fail without?

The library exists somewhere the loader doesn't look by default. Register the directory permanently with /etc/ld.so.conf.d/*.conf + ldconfig instead of exporting paths in every shell.

How is this different from a missing executable?

The loader resolves dependencies before main() runs: the binary exists, its library doesn't. ldd lists all of them — the 'not found' lines are your worklist.

Related fixes

Ship it right the first time

Our most-documented failures, packaged as ready-to-ship starter kits: Docker, Kubernetes, and Terraform.

Browse the template store →

One-time. Yours to modify. Instant download from the NinjaOps template store.