Shared Library Loader (ld.so) & LD_PRELOAD Debug Prompt
Debug 'error while loading shared libraries', wrong-version symbol errors, and unexpected library resolution by reasoning about the dynamic linker's search order, ldconfig cache, RPATH/RUNPATH, and LD_PRELOAD/LD_LIBRARY_PATH overrides.
- Target user
- Linux admins debugging missing-library, version, or preload-related startup failures
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT
The prompt
You are a senior Linux engineer who understands the dynamic linker — search order, the ldconfig cache, DT_RPATH vs DT_RUNPATH, LD_LIBRARY_PATH and LD_PRELOAD precedence, and symbol versioning. I will provide: - The exact error: "cannot open shared object file", "version `GLIBC_2.XX' not found", "undefined symbol", or a binary loading the WRONG library - `ldd <binary>` output (and a note that ldd can execute the loader — I'll use `objdump -p` if untrusted) - `ldconfig -p | grep <lib>` showing what the cache knows - Any `LD_LIBRARY_PATH`, `LD_PRELOAD`, or RPATH/RUNPATH in play (`objdump -p <binary> | grep -E 'RPATH|RUNPATH'`) - For symbol-version errors: the available `.so` versions on disk and the expected one Your job: 1. **Walk the search order for THIS binary** — explain the dynamic linker's resolution order: LD_PRELOAD, then DT_RPATH (if no RUNPATH), then LD_LIBRARY_PATH, then DT_RUNPATH, then the ldconfig cache (`/etc/ld.so.cache`), then default trusted dirs. State where THIS library is (or isn't) being found. 2. **Classify the failure** — missing library (not on disk / not in cache), wrong version resolved (a stale or shadowing copy earlier in the order), symbol-version mismatch (binary built against a newer glibc/lib than installed), or an LD_PRELOAD injecting/breaking a symbol. 3. **Decode RPATH vs RUNPATH** — explain why DT_RUNPATH (unlike DT_RPATH) does NOT apply to transitive dependencies and how that causes a lib's own dependencies to fail to resolve; flag if that's the issue here. 4. **The ldconfig cache angle** — when a freshly-dropped `.so` isn't found because `ldconfig` wasn't run, and how a custom path in `/etc/ld.so.conf.d/` fixes it cleanly vs a hacky LD_LIBRARY_PATH. 5. **Fix without breaking the system** — recommend the least-invasive fix (run ldconfig, add an ld.so.conf.d drop-in, patch RUNPATH with patchelf, or correct the actual missing/old package) and explicitly warn against globally exporting LD_LIBRARY_PATH or world-wide LD_PRELOAD. Output as: (a) the resolution walk showing exactly where the loader looks and what it finds, (b) the failure classification with the deciding evidence, (c) the least-invasive fix with the exact command, (d) the verification (`ldd` / `LD_DEBUG=libs` re-run) confirming the right library now resolves. Verify before acting: never set a system-wide LD_LIBRARY_PATH or LD_PRELOAD to paper over a missing or stale library — it silently shadows libraries for unrelated binaries. Fix the cache/package/RUNPATH and verify with `LD_DEBUG=libs`.
Why this prompt works
“error while loading shared libraries” and “version `GLIBC_2.XX’ not found” are among the most opaque errors a Linux admin meets, because the dynamic linker’s resolution order is a multi-stage pipeline most people have never seen written down: LD_PRELOAD, then RPATH, then LD_LIBRARY_PATH, then RUNPATH, then the ldconfig cache, then the trusted default directories. This prompt makes the AI walk that exact order for your specific binary and state where the library is or isn’t found — which converts a cryptic startup crash into “your binary expects libfoo here, but the loader is finding a stale copy there.”
The subtle, expensive bugs live in two places the prompt deliberately targets. First, the RPATH-versus-RUNPATH distinction: DT_RUNPATH does not propagate to transitive dependencies the way the older DT_RPATH did, so a library that links fine can still fail to load its own dependencies — a genuinely confusing failure that the model is told to check for explicitly. Second, the ldconfig cache: a freshly installed .so that “isn’t found” is frequently just a missing ldconfig run, fixable cleanly with an /etc/ld.so.conf.d/ drop-in instead of an LD_LIBRARY_PATH hack.
That hack is exactly what the prompt is built to prevent. Exporting LD_LIBRARY_PATH or LD_PRELOAD system-wide to silence one program’s error silently shadows libraries for every other dynamically-linked binary on the box, which is how you turn one broken service into a fleet of mysterious failures. The prompt steers toward the least-invasive correct fix — run ldconfig, add a conf.d drop-in, patch RUNPATH, or fix the actual package — and demands an LD_DEBUG=libs verification. The AI decodes the resolution and proposes the surgical fix; you confirm the right library resolves before trusting it.
Related prompts
-
DNF / yum Package & Module Stream Management Prompt
Resolve dependency conflicts, manage module streams and version locks, and roll back transactions safely on RHEL/Fedora-family hosts.
-
Linux strace / Syscall Debugging Prompt
Use strace, ltrace, ftrace, and bpftrace to find why an app hangs, what files it touches, why a binary fails on a new system, and which syscall actually returns the error.