Rust "error: linking with `cc` failed" in CI

The compiler ran fine but the final link step failed. cc exists, yet it could not produce the binary - usually an undefined reference or a system library the build links against but the runner doesn’t have.

What this error means

The build reaches error: linking with cc failed: exit status: 1 followed by linker output. Unlike "linker cc not found", here the linker runs - the failure is in the link itself (missing -l library, undefined symbols).

cargo output

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

error: linking with `cc` failed: exit status: 1

Common causes

A required system library is missing

A -sys crate links against an OS library (-lpq, -lssl, -lz). If the dev package isn’t installed, ld reports cannot find -l<name>.

Undefined symbols or ABI mismatch

A native dependency expects symbols absent from the installed library version, or mixes incompatible C/C++ runtimes, producing undefined-reference link errors.

How to fix it

Install the missing library

Map the cannot find -l<name> to its dev package and install it.

Terminal

# example: -lpq needs libpq-dev
apt-get update && apt-get install -y libpq-dev pkg-config

Read the linker note carefully

Scroll into the = note: block - the real ld error is there.
For cannot find -lX, install the -dev package providing libX.
For undefined references, check the native lib version matches what the -sys crate expects.

How to prevent it

Install pkg-config and the dev libraries your -sys crates need.
Bake those system libraries into the runner image.
Pin native dependency versions so the linked ABI stays stable.