Rust "linking with cc failed: undefined reference" in CI

The compile succeeded but the linker could not resolve a C symbol. A -sys crate references a function in a native library that was never passed to the linker, so the final link fails.

What this error means

The build ends with error: linking with cc failed: exit status: 1 and a block of undefined reference to X`` lines from the linker. It is deterministic given the same system libraries.

cargo

error: linking with `cc` failed: exit status: 1
  |
  = note: /usr/bin/ld: target/debug/deps/app: undefined reference to `SSL_new'
          /usr/bin/ld: undefined reference to `SSL_connect'
          collect2: error: ld returned 1 exit status

Common causes

Native library not linked

A -sys crate declares symbols from a system library (libssl, libz) but the library is absent or not on the linker search path, so the symbols stay unresolved.

ABI or version mismatch

Linking against a different major version of the C library than the crate expects can drop or rename symbols.

How to fix it

Install the native library and its dev headers

Provide the library the -sys crate links against.

.github/workflows/ci.yml

sudo apt-get update
sudo apt-get install -y libssl-dev zlib1g-dev pkg-config

Point the linker at the library directory

If the library lives in a non-standard path, add it to the search path.

Terminal

export RUSTFLAGS="-L /usr/local/lib"
cargo build --locked

How to prevent it

Install the -dev packages every -sys crate needs before building.
Pin the native library major version to match the crate.
On Latchkey managed runners you can bake the required native dev libraries into the runner image so every build links cleanly.