Rust "linker `lld` not found" - Missing Alternative Linker in CI

By Kaveh Alemi·Latchkey

Your Cargo config tells rustc to link with lld (or mold), but that linker isn’t installed on the runner. The build can’t link until you install the chosen linker or remove the override.

What this error means

Linking fails with linker lld not found (or mold), even though the default cc exists. It appears after someone adds a fast-linker rustflags/linker override to .cargo/config.toml that the CI image doesn’t satisfy.

error: linker `lld` not found
  |
  = note: No such file or directory (os error 2)

error: could not compile `app` (bin "app") due to 1 previous error

Common causes

Config selects an uninstalled linker

A .cargo/config.toml sets linker = "lld" or -fuse-ld=mold to speed up links locally, but the CI image ships neither, so rustc can’t invoke it.

Wrong binary name for the linker

The linker is installed under a different name (ld.lld, rust-lld, mold) than the config references, so it isn’t found on PATH.

How to fix it

Install the linker the config asks for

# lld
apt-get update && apt-get install -y lld
# mold
apt-get update && apt-get install -y mold

Or drop the override in CI

If you don’t need the fast linker on the runner, remove or guard the linker setting so rustc uses the default cc.

# .cargo/config.toml - point at an installed linker explicitly
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=lld"]

How to prevent it

• Install lld/mold in the image when .cargo/config.toml selects them.
• Keep linker overrides target-scoped so they only apply where the linker exists.
• Document the linker your config requires alongside the build instructions.

Frequently asked questions

Related guides

References

• The Cargo Book
• GitHub Actions documentation