cargo 'failed to load source for dependency X' - how to fix
Fixes cargo's failed to load source for a dependency. Use it when cargo cannot fetch a registry or git source. Key trigger: the failed to load source line naming the dependency and its source. Not for version-resolution or checksum failures.
TL;DR
cargo cannot fetch the dependency's source: a git URL it cannot reach, or a registry it cannot download from. Identify which source failed, verify it is reachable, then retry the fetch. The manifest entry is usually fine; the network path is not.
Error
cargo 'failed to load source for dependency X' - how to fixSteps
Read the error for the source kind: a git URL versus the registry. Expected output: You know whether to debug git access or registry access.
For a git dependency, verify the URL and rev: try fetching the repo with git directly. Expected output: Either git succeeds (transient cargo issue) or it fails the same way (bad URL, missing rev, auth).
For a registry dependency, check network access to the registry and index; retry cargo fetch. Expected output: cargo downloads the crate sources.
Clear a poisoned cache entry if one fetch corrupted it: remove the crate from the registry cache and fetch again. Expected output: A clean download replaces the bad cache entry.
Build to confirm: cargo build. Expected output: All sources load and the build proceeds.
When to use
- cargo fails with failed to load source for dependency X
- A git dependency points at a moved repo, a deleted branch, or a private repo without credentials
- The registry is reachable for browsing but cargo cannot download
When not to use
- cargo cannot find the package name at all; that is a resolution error, not a source error
- The download succeeds but the checksum fails; that is an integrity error
- The manifest has a typo in the version; fix the version instead
Variant phrasings
cargo failed to load source for a git dependency
The git shape: URL, rev, or credentials are the suspects.
failed to load source from the registry behind a proxy
The proxy shape: cargo needs the proxy configured where git and curl already work.
Intermittent failed to load source in CI
Transient network blips; retry the fetch step before re-resolving.
Why it happens
cargo separates resolving (picking versions) from loading sources (downloading them). Resolution can succeed against the index while the actual download fails: the git remote moved, the rev was force-pushed away, the registry is down, or a proxy blocks cargo but not the browser. The error names the source so you debug the fetch, not the version pick.
Edge cases
- SSH git URLs need keys available to the cargo process; HTTPS URLs need credential helpers in CI.
- A force-pushed branch moves the rev the lockfile recorded; pin tags or full SHAs for stability.
- Corporate proxies often require config in cargo's own config file, not just env vars.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_1EohZbCWrSsoFBjYT7B7Qw