Cargo "failed to download from crates.io: SSL/TLS" in CI

By Kaveh Alemi·Latchkey

Cargo could not complete the TLS handshake when fetching a crate from crates.io. Either the connection dropped mid-transfer (a transient network blip) or the runner lacks the CA certificates needed to verify crates.io.

What this error means

The build fails with error: failed to download from https://...crates.io...` and a Caused by:` TLS/SSL line. Transient cases pass on retry; missing-CA cases fail every run.

cargo

error: failed to download from `https://static.crates.io/crates/serde/serde-1.0.0.crate`

Caused by:
  [35] SSL connect error (schannel: failed to receive handshake, SSL/TLS connection failed)

Common causes

Transient TLS handshake failure

A dropped connection or a brief crates.io/CDN hiccup interrupts the TLS handshake mid-download.

Missing or stale CA certificates

A minimal runner image without ca-certificates cannot verify the TLS chain, so every download fails.

How to fix it

Install CA certificates and raise retries

Ensure the trust store is present and let cargo retry transient drops.

.github/workflows/ci.yml

sudo apt-get update && sudo apt-get install -y ca-certificates
export CARGO_NET_RETRY=10
cargo fetch --locked

Cache the registry between runs

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: |
      ~/.cargo/registry
      ~/.cargo/git
    key: cargo-${{ hashFiles('Cargo.lock') }}

How to prevent it

Install ca-certificates on minimal runner images.
Set CARGO_NET_RETRY high enough to absorb a transient blip.
On self-healing managed runners (Latchkey), transient TLS download failures are auto-retried and the cargo registry is cached, so a flaky handshake does not fail the build.

Frequently asked questions

What causes ""failed to download: TLS""?