Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

.NET in Docker cannot load libldap for LDAP or Active Directory

ErrorUnable to load shared library 'libldap-2.4.so.2' or one of its dependencies

Short answer

On Linux, .NET's LDAP code loads the OpenLDAP library at run time, and the .NET images do not ship it. Install the libldap package for your base image in the final stage. On Ubuntu 24.04 the file is named libldap.so.2, while the runtime may look for a versioned name.

  • Applies to .NET 8, .NET 9, Debian and Ubuntu 24.04 base images, Alpine
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether any libldap file exists in the running image. Run this inside the container.

    docker run --rm --entrypoint sh my-image -c 'ls /usr/lib/*/libldap* /usr/lib/libldap* 2>/dev/null'
  2. 2Match what you see, then jump to its fix

    1. 1The ls command prints nothinglibldap is not in the image at allFix
    2. 2Error names libldap-2.5.so.0 on Ubuntu 24.04, and libldap.so.2 existsThe library is installed under a name the runtime does not look forFix

What does the error look like?

  • Unable to load shared library 'libldap-2.4.so.2' or one of its dependencies
  • Unable to load shared library 'libldap-2.5.so.0' or one of its dependencies
  • System.TypeInitializationException for the Ldap type

Cause 1 of 2

libldap is not in the image at all

1Check

The .NET team decided not to include libldap in its container images for any distro. It is opt-in, so every app that uses LdapConnection has to add it.

docker run --rm --entrypoint sh my-image -c 'ls /usr/lib/*/libldap*'

2Fix

Install the package in the final stage of your Dockerfile. Names differ by distro: libldap2 on Ubuntu 24.04, libldap-2.4-2 on older Debian releases, libldap on Alpine.

# Ubuntu 24.04 / Debian based final stage
USER root
RUN apt-get update && apt-get install -y --no-install-recommends libldap2 \
    && rm -rf /var/lib/apt/lists/*
# Alpine final stage
# RUN apk add --no-cache libldap

3Verify

Rebuild and run the LDAP code again.

docker run --rm --entrypoint sh my-image -c 'ls /usr/lib/*/libldap*'

Confirmed by github.com

Did this fix it?

Cause 2 of 2

The library is installed under a name the runtime does not look for

1Check

The .NET repository reports that the runtime tries versioned names (libldap-2.6.so.0, libldap-2.5.so.0, libldap-2.4.so.2), while Ubuntu 24.04 ships libldap.so.2. That issue is open and its fix is not confirmed for every .NET version.

docker run --rm --entrypoint sh my-image -c 'ls -l /usr/lib/*/libldap* /usr/lib/*/liblber*'

2Fix

Users in the project's issue report a symlink from the expected name to the installed file as a workaround, together with the libldap2 package. It is not an official fix, so test it.

RUN ln -s /usr/lib/x86_64-linux-gnu/libldap.so.2 /usr/lib/x86_64-linux-gnu/libldap-2.5.so.0 \
 && ln -s /usr/lib/x86_64-linux-gnu/liblber.so.2 /usr/lib/x86_64-linux-gnu/liblber-2.5.so.0

3Verify

Run the LDAP call again and confirm the exception is gone.

docker run --rm my-image

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Add the libldap package to the final stage, not only the build stage: the SDK image can work while the runtime image fails.
  • Pick the library package name from your base image's distro, and check it again when you change base image.
  • Read the .NET issue tracker for libldap when you upgrade the runtime or the base image.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

sail up fails with a permission error

WARNING: Error loading config file: /home/user/.docker/config.json - stat /home/user/.docker/config.json: permission denied

A permission error from sail up has three documented sources on Linux: Docker Desktop is using the wrong context, files inside the container are not writable by the container user, or Docker's own config folder is owned by root from an earlier sudo run.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.