Rust cross-compilation linker not found in CI

You cross-compiled for a non-host target (aarch64, arm, musl) but the linker that target needs is not installed. rustc invokes the platform linker by name; when that binary is absent, the link step fails.

What this error means

The build fails with error: linker aarch64-linux-gnu-gcc not found (or a musl-gcc / arm equivalent). It is deterministic for the runner image and target.

cargo

error: linker `aarch64-linux-gnu-gcc` not found
  |
  = note: No such file or directory (os error 2)

error: could not compile `app` (bin "app")

Common causes

Cross linker not installed

Cross-compiling needs the target's GCC/linker (aarch64-linux-gnu-gcc, musl-gcc); a stock runner does not have it.

Linker installed but not configured

The linker exists but cargo was not told to use it for that target via target.<triple>.linker.

How to fix it

Install the cross toolchain and point cargo at it

Install the linker and configure it for the target.

.github/workflows/ci.yml

sudo apt-get update
sudo apt-get install -y gcc-aarch64-linux-gnu
mkdir -p .cargo
printf '[target.aarch64-unknown-linux-gnu]\nlinker = "aarch64-linux-gnu-gcc"\n' >> .cargo/config.toml
rustup target add aarch64-unknown-linux-gnu
cargo build --target aarch64-unknown-linux-gnu --locked

Use cross for a containerized toolchain

cross bundles the right linker per target in a container.

Terminal

cargo install cross
cross build --target aarch64-unknown-linux-gnu --locked

How to prevent it

Install the matching cross linker for every non-host target you build.
Configure target.<triple>.linker in .cargo/config.toml.
On Latchkey managed runners you can bake the cross toolchains into the runner image so cross builds link without per-job installs.