ld "cannot find -lXXX" - Missing Library at Link Time

The linker was told to link a library with -lXXX but could not find libXXX.so/libXXX.a in any search directory. The library’s development package is missing, or its directory is not on the link path.

What this error means

Link fails with "/usr/bin/ld: cannot find -lXXX" and then "collect2: error: ld returned 1 exit status". Compilation succeeded; only the link step can’t locate the library file.

/usr/bin/ld: cannot find -lpq: No such file or directory
collect2: error: ld returned 1 exit status

Common causes

Development library not installed

The -dev/-devel package that ships the linkable libXXX.so (e.g. libpq-dev for -lpq) is absent on the CI image. A runtime-only package does not include the unversioned .so symlink the linker needs.

Library directory not on the search path

The library is in a custom prefix the linker does not search; without -L<dir> (or it on the CMake target), ld cannot find it.

How to fix it

Install the development package

# Debian/Ubuntu - provides linkable libpq.so for -lpq
apt-get update && apt-get install -y libpq-dev
# Fedora/RHEL
# dnf install -y libpq-devel

Add the library search directory

For a library in a custom prefix, add -L (and at runtime, the rpath).

g++ main.o -o app -L/opt/pg/lib -lpq -Wl,-rpath,/opt/pg/lib
# CMake:
# target_link_directories(app PRIVATE /opt/pg/lib)

How to prevent it

• Install all -dev/-devel libraries your link line needs in the runner image.
• Use find_package/imported targets so library locations are resolved by CMake.
• Add custom prefixes via CMAKE_PREFIX_PATH rather than ad hoc -L flags.

Related guides