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

By Daniel Zoghalchali·Latchkey

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.

Frequently asked questions

What causes ""linking with cc failed""?

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

How do I fix "linking with cc failed"?

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

Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.