rustup "could not choose a version of cargo" (missing toolchain) in CI

cargo is a rustup proxy. When rustup has no default toolchain and the directory override (rust-toolchain.toml) points at a toolchain that is not installed, rustup cannot pick a version to run and aborts.

What this error means

A cargo step fails with "error: rustup could not choose a version of cargo to run, because one wasn't specified explicitly, and no default is configured".

rustup

error: rustup could not choose a version of cargo to run, because one wasn't
specified explicitly, and no default is configured.
help: run 'rustup default stable' to download the latest stable release of Rust
and set it as your default toolchain.

Common causes

No default toolchain configured

rustup is installed but rustup default was never set on the runner, so a bare cargo has nothing to proxy to.

An override toolchain that is not installed

A rust-toolchain.toml pins a channel that has not been installed on the runner, so the override resolves to a missing toolchain.

How to fix it

Set a default toolchain

Install and select a default so bare cargo works. The toolchain action does this cleanly.

.github/workflows/ci.yml

- uses: dtolnay/rust-toolchain@stable
- run: cargo build --locked

Install the pinned override toolchain

If a rust-toolchain.toml pins a channel, install it explicitly before building.

Terminal

rustup toolchain install 1.79.0
cargo build

How to prevent it

Install and set a default toolchain early in the job.
Install any channel that rust-toolchain.toml pins.
Use a toolchain action that provisions and selects rustc for you.