1.2.1.3 Missing Runtime Libraries

Missing runtime libraries are shared libraries or system-level packages that an application needs in order to run, but that are not present on the machine attempting to run it, typically causing the application to fail immediately at startup with an error naming the missing library.

How Missing Libraries Cause Failures

Many applications, especially those written in compiled languages like C, C++, or Go with certain build configurations, link against shared libraries provided by the operating system rather than bundling them. If a target machine does not have the expected library installed — or has an incompatible version of it — the application fails to start.

error while loading shared libraries: libssl.so.1.1: cannot open shared object file: No such file or directory

This kind of error has nothing to do with the application's logic; it is purely a consequence of the host machine's package set differing from the machine the application was built or tested on.

Why This Happens More Often Across Environments

A library that is installed on a developer's machine because some other application also needed it can create a false sense that the dependency is satisfied everywhere, when in fact a fresh server or a colleague's machine without that other application would be missing it entirely.

Eliminating Missing Libraries With Image Packaging

A Docker image declares every system-level package the application needs as part of its build definition, so the resulting container always has exactly the libraries the application requires, regardless of what is or is not installed on the host.

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y libssl3 libpq5
COPY app /usr/local/bin/app
CMD ["app"]

Because the host's installed packages are irrelevant to what runs inside the container, the question of whether a given library exists on this particular host stops being a source of failure.

Diagnosing Missing Library Errors

When a missing library error does occur — typically while building the image itself — the fix is to add the missing package to the Dockerfile, not to install it manually on a running container, since a manual fix would not persist if the container were ever recreated.

docker run --rm -it debian:bookworm-slim bash
apt-get update && apt-get install -y libssl3
ldd /usr/local/bin/app

The ldd command lists every shared library a binary depends on and shows which ones, if any, cannot be found, making it straightforward to identify exactly what is missing before adding it to the image definition.

Static Linking as an Alternative

Some languages, such as Go, can produce statically linked binaries that bundle their dependencies directly into the executable, removing the missing-library problem entirely by not relying on the host's shared libraries at all.

CGO_ENABLED=0 go build -o app .