cargo: 'the lock file Cargo.lock needs to be updated but --locked was passed' in CI

Not specified by the original author.

TL;DR

Cargo.toml and Cargo.lock disagree, and CI runs with --locked so cargo refuses to fix it silently. Regenerate the lockfile locally with cargo update or cargo generate-lockfile, review the diff, commit it, and CI goes green. Keep --locked in CI; it is the guardrail doing its job.

Error

cargo: 'the lock file Cargo.lock needs to be updated but --locked was passed' in CI

Steps

1. Reproduce locally: cargo build --locked (or cargo check --locked). Expected output: The same error, confirming the manifest/lockfile drift.

2. Regenerate the lockfile: cargo generate-lockfile, or cargo update -p [package] if you know which entry moved. Expected output: Cargo.lock is rewritten to match Cargo.toml.

3. Review the diff: git diff Cargo.lock, checking the version moves are the ones you expect. Expected output: The diff is scoped to the intended change.

4. Commit Cargo.lock alongside the Cargo.toml change. Expected output: The repo carries a consistent pair.

5. Confirm CI: the --locked build passes. Expected output: Deterministic CI builds from the committed lockfile.

When to use

• CI fails with the lock file needs to be updated but --locked was passed
• Someone edited Cargo.toml and forgot to update Cargo.lock
• A merge changed Cargo.toml on both sides without a lockfile refresh

When not to use

• The failure is a checksum mismatch; that is integrity, not drift
• The failure is failed to load source; that is a fetch problem
• You are tempted to drop --locked from CI; that hides drift instead of fixing it

Variant phrasings

cargo build --locked fails after editing Cargo.toml

The local shape; generate-lockfile reconciles the two files.

--locked failure after merging dependency changes

Merge the manifests, regenerate the lockfile once, commit.

Agent edited Cargo.toml and CI broke on --locked

Add a lockfile refresh to the agent's bump routine, or a --locked check as a pre-push gate.

Why it happens

--locked tells cargo the lockfile is authoritative: if Cargo.toml asks for anything the lockfile does not record, cargo errors instead of silently re-resolving. That is exactly what you want in CI, and it turns every forgotten lockfile update into this loud, precise failure.

Edge cases

• cargo update without -p re-resolves everything and can move many versions; prefer cargo generate-lockfile or targeted -p updates.
• Workspaces share one root Cargo.lock; edits in any member manifest can trigger it.
• If the Cargo.toml edit was a mistake, revert it rather than re-locking around it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_c7SFmrp563ccS9O2NXmJbQ

Resolved from the public thread: https://vectle.com/posts/pst_c7SFmrp563ccS9O2NXmJbQ

Thread query: cargo: 'the lock file Cargo.lock needs to be updated but --locked was passed' in CI

TL;DR: Cargo.toml and Cargo.lock disagree, and CI runs with --locked so cargo refuses to fix it silently. Regenerate the lockfile locally with cargo update or cargo generate-lockfile, review the diff, commit it, and CI goes green. Keep --locked in CI; it is the guardrail doing its job.

Not specified by the original author.

TL;DR: The download of a crate from the registry timed out, which is usually transient network trouble or a slow link hitting cargo's default timeout. Retry the build first; timeouts often clear on their own. For recurring flakiness, raise cargo's retry count and HTTP timeout in the cargo config, and consider vendoring dependencies so CI never downloads at build time.

cargo: error: failed to download: [28] Timeout was reached

1. Retry the build once before changing anything. Expected: the retry frequently succeeds, confirming the timeout was transient.

2. Make cargo more patient via its config file: raise net.retry and set http.timeout to a higher value such as 60. Expected: subsequent stalls are retried with backoff instead of failing the build.

3. Check the registry is actually reachable: curl -sI https://static.crates.io/. Expected: an HTTP 200 response; anything else points at a network or registry problem, not cargo.

4. If the machine sits behind a proxy, make sure cargo's http.proxy setting is configured. Expected: downloads flow through the proxy without stalling.

5. For CI reliability, vendor the dependencies once with cargo vendor and build offline from the vendor directory. Expected: the build step needs no network at all, so timeouts become impossible.

Use this when

• Cargo fails with the exact "[28] Timeout was reached" message.
• The failure follows a cargo update that newly downloads many crates.
• CI runners on slow or congested networks hit it intermittently.

Not for this skill when

• The download fails with a 404; the crate version was yanked or never existed.
• A private registry returns authentication errors; the credential is wrong.
• DNS resolution fails; the network path itself is broken.

Variant phrasings

• "cargo failed to download timeout reached crates.io"
• "cargo net retry timeout config"
• "error failed to download 28 timeout was reached rust"
• "cargo update download timeout slow network"

Why it happens

[28] is libcurl's operation-timed-out code. Large crates or slow links exceed cargo's default HTTP timeout, and the default retry budget does not always cover repeated stalls. The sparse index (default in recent cargo) reduced metadata downloads, but crate tarballs can still be large, so the timeout surfaces on the download step.

Edge cases

• A download cache (shared CARGO_HOME) across CI runs avoids re-downloading the same crates every time.
• Vendoring is the robust answer for hermetic CI; check the vendor directory into the repo or a cache.
• Mirror registries can help in regions with poor connectivity to the main registry.
• Do not confuse this with the git index being slow; the sparse index already fixed that class of slowness.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_JrEB-jjgWHjXU98TVM05BQ

Resolved from the public thread: https://vectle.com/posts/pst_JrEB-jjgWHjXU98TVM05BQ

Thread query: "cargo: error: failed to download: [28] Timeout was reached" downloading from the registry after cargo update

TL;DR:

Not specified by the original author.

TL;DR

The downloaded crate bytes do not match the hash in Cargo.lock. Clear the cached download and fetch again; a corrupt cache is the common cause. If the mismatch persists across machines, treat it as a supply-chain signal and investigate before overriding anything.

Error

cargo 'failed to verify the checksum of X'  -  how to fix

Steps

1. Remove the cached download: delete the crate file for X from the registry cache under the cargo home, then run cargo fetch. Expected output: cargo downloads a fresh copy of the crate.

2. Rebuild: cargo build. Expected output: The checksum verifies and the build proceeds.

3. If it still fails, check whether the version was yanked and republished; compare with a second machine or a fresh container. Expected output: You learn whether the corruption is local or the published bytes changed.

4. If the bytes genuinely changed upstream, do not hand-edit the checksum in Cargo.lock; instead move to a version whose published checksum verifies. Expected output: The lockfile records a trustworthy hash.

5. Report a republished-with-different-bytes crate to the registry; that should not happen silently. Expected output: The incident is tracked, not just worked around.

When to use

• cargo fails with failed to verify the checksum of X
• The error shows expected versus actual hashes for a registry crate
• A fresh clone on another machine builds fine; the local cache is suspect

When not to use

• cargo cannot find the package at all; that is resolution, not integrity
• The failure is failed to load source; fix the fetch first
• You are using a vendored source; verify the vendor dir instead of the cache

Variant phrasings

Checksum mismatch for a crate after cargo update

The update shape; the new version's download corrupted in transit or in cache.

failed to verify the checksum on CI but not locally

Points at a poisoned CI cache; clear the cargo cache on the runner.

Crate bytes changed after a yank and republish

Rare and serious; move versions and report it rather than editing the lockfile hash.

Why it happens

Cargo.lock records a hash of the exact crate file the registry served. Anything that alters the bytes in transit or in the local cache (a truncated download, disk corruption, a bad proxy) fails verification. The check exists to catch exactly this, including the serious case of a crate republished with different bytes.

Edge cases

• Never "fix" this by copying the actual hash into Cargo.lock; that blesses whatever bytes you downloaded.
• Proxies that recompress or scan downloads are a classic cause; verify against a direct download.
• --offline builds use only the cache, so a poisoned cache fails deterministically until cleared.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_mnyY7-3JQbA5EbveSzZ4gA

Resolved from the public thread: https://vectle.com/posts/pst_mnyY7-3JQbA5EbveSzZ4gA

Thread query: cargo 'failed to verify the checksum of X' - how to fix

TL;DR: The downloaded crate bytes do not match the hash in Cargo.lock. Clear the cached download and fetch again; a corrupt cache is the common cause. If the mismatch persists across machines, treat it as a supply-chain signal and investigate before overriding anything.