entry point not found: The Five Causes on Windows, Linux, and macOS and How to Diagnose Each

“Entry point not found” is one of those errors that shows up the first time a binary runs in a new environment. The binary needs a function or symbol from a library, and the library is missing, wrong version, or in the wrong place. The error is generic; the cause is specific. The honest version covers the five causes (missing DLL, version mismatch, wrong architecture, missing symbol, broken PATH), the OS-specific tool to find the missing entry (Windows: dependency walker, Linux: ldd, macOS: otool), and the three fixes that work in 90% of cases.

Table of contents

• Table of contents
• The direct answer
• The five causes
• Cause 1: missing shared library
• Cause 2: version mismatch
• Cause 3: wrong architecture
• Cause 4: missing symbol within a library
• Cause 5: PATH / LD_LIBRARY_PATH / DYLD_LIBRARY_PATH
• The OS-specific diagnostic tools
• The three fixes that work in 90% of cases
• FAQ
• FAQ

The short version: identify whether the entry point is in a shared library (DLL/.so/.dylib) or a symbol within a binary, find the library that is supposed to provide it, verify the version, and either install the right version or set the right PATH. The cause is almost always one of five things.

Table of contents

• The direct answer
• The five causes
• Cause 1: missing shared library
• Cause 2: version mismatch
• Cause 3: wrong architecture
• Cause 4: missing symbol within a library
• Cause 5: PATH / LD_LIBRARY_PATH / DYLD_LIBRARY_PATH
• The OS-specific diagnostic tools
• The three fixes that work in 90% of cases
• FAQ

The direct answer

The error message in full:

The code execution cannot proceed because <library>.dll was not found.

or on Linux:

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

or on macOS:

Library not loaded: libfoo.dylib
Reason: image not found

The first step: identify which library is missing. The error message names it.

The second step: find where that library should live. On Windows: C:\Windows\System32 or the application’s directory. On Linux: /usr/lib, /usr/local/lib, or a path in LD_LIBRARY_PATH. On macOS: /usr/lib, /usr/local/lib, or a path in DYLD_LIBRARY_PATH.

The third step: either install the missing library or set the PATH so the binary can find it.

The five causes

1. Missing shared library. The library is not on the system. Install it.
2. Version mismatch. The library is installed but a different version. The binary needs version 2.x and finds version 1.x. Install the right version or update the binary.
3. Wrong architecture. The library is the wrong bitness (32-bit vs 64-bit). On Linux, libfoo.so vs libfoo32.so. On Windows, foo.dll vs foo64.dll. Install the right one.
4. Missing symbol within a library. The library is installed but a specific function the binary needs is not exported. This is rare; usually means a different library version.
5. PATH / LD_LIBRARY_PATH / DYLD_LIBRARY_PATH. The library is installed but not in a location the binary searches. Add the path.

Cause 1: missing shared library

The simplest cause. The binary needs libfoo.so.2 and the system does not have it.

On Debian/Ubuntu: apt install libfoo2 (the package name usually matches the library name).

On RHEL/CentOS/Fedora: dnf install foo-libs or yum install foo-libs.

On Alpine: apk add libfoo.

On macOS with Homebrew: brew install foo.

On Windows: download the DLL from the library’s official distribution. Do not download DLLs from random “DLL download” sites — those are a malware vector.

The fix in CI: add the library to your Dockerfile (RUN apt-get install -y libfoo2) or your build script.

Cause 2: version mismatch

The library is installed but a different version. The binary needs libfoo.so.2 and finds libfoo.so.1.

On Linux, the version is encoded in the filename (libfoo.so.1, libfoo.so.2). The binary loads the specific version it was linked against.

The diagnostic:

ldd ./mybinary
# libfoo.so.2 => not found

The not found means the binary was linked against libfoo.so.2 but the system only has libfoo.so.1.

The fix: install version 2.x of the library. Or update the binary to be compatible with version 1.x. Or use a compatibility shim (libfoo.so.1 symlinked to libfoo.so.2, but this is fragile).

In a Docker image, the most common cause is a FROM base image that has older libraries. Switch to a newer base image or install the libraries explicitly.

Cause 3: wrong architecture

The binary is 64-bit but the library is 32-bit (or vice versa). On Linux, this shows up as libfoo.so: wrong ELF class or simply not finding the library.

The diagnostic:

file ./mybinary
# ELF 64-bit LSB executable, x86-64

file /usr/lib/libfoo.so
# ELF 32-bit LSB shared object, Intel 80386

Different architectures. The binary cannot load the library.

The fix: install the matching architecture. On Debian/Ubuntu: apt install libfoo:i386 for 32-bit libraries on a 64-bit system. Or install the 64-bit library if your binary should be 64-bit.

On Apple Silicon Macs (M1/M2/M3): this used to be a common problem with x86_64-only binaries. Rosetta 2 handles the translation, but native arm64 binaries are faster. Rebuild for arm64 if possible.

On Windows: a 64-bit binary loads 64-bit DLLs from System32. A 32-bit binary loads 32-bit DLLs from SysWOW64. Mixing causes “entry point not found.”

Cause 4: missing symbol within a library

The library is installed and the right version, but a specific function the binary needs is not exported. This is rare; usually it means a different build configuration.

The diagnostic:

nm -D /usr/lib/libfoo.so | grep my_function
# If no output: the function is not in this library.

nm -D lists exported dynamic symbols. If the function is not there, you have the wrong library.

The fix: install the right library version (with the symbol), or rebuild the binary against the library version you have.

For Python native modules: the symbol is usually a PyInit function. If you see undefined symbol: PyInit_foo, the module was compiled against a different Python version than the one running.

Cause 5: PATH / LD_LIBRARY_PATH / DYLD_LIBRARY_PATH

The library is installed but not in a location the binary searches. The fix is to add the path.

On Linux:

# Check the current library path
echo $LD_LIBRARY_PATH

# Add a directory
export LD_LIBRARY_PATH=/opt/myapp/lib:$LD_LIBRARY_PATH

# Or for the whole system, add to /etc/ld.so.conf.d/myapp.conf
echo "/opt/myapp/lib" | sudo tee /etc/ld.so.conf.d/myapp.conf
sudo ldconfig

ldconfig rebuilds the library cache. After adding a path, run ldconfig so the dynamic linker finds the new library.

On macOS:

export DYLD_LIBRARY_PATH=/opt/myapp/lib:$DYLD_LIBRARY_PATH

Note: macOS’s DYLD_LIBRARY_PATH is often stripped by the system for security (System Integrity Protection). For system-wide changes, use install_name_tool to update the binary’s library references.

On Windows:

Add the directory to the system PATH:

System Properties > Advanced > Environment Variables > Path > Edit

Or set PATH for the current process:

set PATH=C:\myapp\lib;%PATH%

The OS-specific diagnostic tools

Windows: Dependency Walker. A free tool (dependencywalker.com) that shows exactly which DLLs a binary depends on and which functions it imports. The “Entry Point Not Found” error is usually a missing import.

For modern Windows: dumpbin /dependents mybinary.exe (Visual Studio command prompt) shows the same info.

Linux: ldd. Shows the shared libraries a binary depends on and where each is found (or “not found”):

ldd ./mybinary
# libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0
# libfoo.so.2 => not found

ldd ./mybinary is the first diagnostic. If a library is “not found”, that is your problem.

For more detail: readelf -d ./mybinary | grep NEEDED shows the exact library names the binary was linked against.

macOS: otool -L. Shows the dynamic libraries a binary depends on:

otool -L ./mybinary
# /usr/lib/libSystem.B.dylib
# @rpath/libfoo.dylib

The @rpath entries mean the library path is stored in the binary’s runpath. Check with otool -l ./mybinary | grep LC_RPATH.

The three fixes that work in 90% of cases

Fix 1: install the missing library. The error message names the library. Find the package that provides it and install it. On Debian/Ubuntu: apt search libfoo to find the package name. On RHEL/CentOS: dnf provides libfoo.so.

Fix 2: set the library path. The library is installed but not in a default location. Add the directory to LD_LIBRARY_PATH (Linux), DYLD_LIBRARY_PATH (macOS), or PATH (Windows). Or install the library to a default location.

Fix 3: install the right version. The library is the wrong version. Install the specific version the binary needs. Most package managers let you specify a version (apt install libfoo2=2.5.0-1).

If those three do not fix it, the cause is usually deeper (custom build, broken symlink, conflicting libraries). At that point, the diagnostic tools above tell you exactly which.

If you are debugging “entry point not found” in a Docker container, the cause is almost always Fix 1 or Fix 3 — a missing library in the image. Add the package to the Dockerfile, rebuild, run. If you are deploying to a managed platform like RunxBuild’s backend services, the build image is reproducible; the libraries that work in the build are the libraries that work at runtime. For what running that binary at production scale costs, the RunxBuild hosting calculator gives you the per-month number.

FAQ

What is an “entry point” in a shared library?

A function that the library exports for other code to call. On Windows, the entry point has a name like _foo@8 (decorated with the calling convention). On Linux, it is just foo.

How do I find which library provides an entry point?

Use nm -D /path/to/library | grep <symbol> to search for the symbol in a specific library. Or use ldd to see which libraries a binary depends on. On Windows, Dependency Walker shows the imports.

Can I have two versions of the same library on the system?

Yes. On Linux, install them with different version suffixes (libfoo.so.1, libfoo.so.2). On Windows, install them in different directories and use the application-specific PATH. macOS does this poorly — the system usually has one version of each library.

Why does my program work on my dev box but not on the server?

The dev box has different libraries installed. Use the same base image in Docker for dev and prod. Or use a tool like Nix to pin the exact dependencies.

What is the difference between LD_LIBRARY_PATH and ld.so.conf?

LD_LIBRARY_PATH is an environment variable, set per-process. ld.so.conf (and /etc/ld.so.conf.d/*.conf) is a system-wide configuration. Both add directories to the dynamic linker’s search path. System-wide is preferred for shared libraries; LD_LIBRARY_PATH is useful for application-specific libraries.

How do I find the version of a library on Linux?

dpkg -l libfoo (Debian/Ubuntu) or rpm -q foo-libs (RHEL/CentOS) shows the installed package version. For the actual .so file: objdump -p /usr/lib/libfoo.so | grep SONAME shows the SONAME version.

Why does Windows show “DLL not found” but Linux shows “shared object not found”?

Same error, different terminology. Windows uses DLL (Dynamic Link Library). Linux uses shared object (.so). macOS uses dynamic library (.dylib). All three are shared libraries.

Can a “missing” entry point actually be a typo in the binary?

Yes. If the binary was compiled against a header that declared foo() but the library exports bar(), the linker catches it at build time. But if the binary was built against version A and then loaded against version B with a renamed function, the entry point is missing.

FAQ

What is an “entry point” in a shared library?

A function that the library exports for other code to call.

How do I find which library provides an entry point?

Use nm -D /path/to/library | grep <symbol> to search for the symbol in a specific library. Or use ldd to see which libraries a binary depends on.

Can I have two versions of the same library on the system?

Yes. On Linux, install them with different version suffixes. On Windows, install them in different directories.

Why does my program work on my dev box but not on the server?

The dev box has different libraries installed. Use the same base image in Docker for dev and prod.

What is the difference between LD_LIBRARY_PATH and ld.so.conf?

LD_LIBRARY_PATH is an environment variable, set per-process. ld.so.conf is system-wide. System-wide is preferred for shared libraries.

How do I find the version of a library on Linux?

dpkg -l libfoo (Debian) or rpm -q foo-libs (RHEL). For the .so file: objdump -p /usr/lib/libfoo.so | grep SONAME.

Why does Windows show “DLL not found” but Linux shows “shared object not found”?

Same error, different terminology. Windows uses DLL, Linux uses .so, macOS uses .dylib. All are shared libraries.

Can a “missing” entry point actually be a typo in the binary?

Yes. If the binary was built against version A and loaded against version B with a renamed function, the entry point is missing.