Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Cargo: failed to select a version for a requirement

Candidates exist but none match, or two requirements cannot unify. Read the graph before touching Cargo.lock.

~5 min readRust
#Rust#Cargo#Dependencies#Build
Two cargo crates pulling one shared crate in opposite directions with an amber no-match gap

Introduction & Quick Summary

Cargo stops with:

code
error: failed to select a version for the requirement `time = "^0.3.20"` candidate versions found which didn't match: 0.3.19, 0.3.18, 0.3.17, ... location searched: crates.io index required by package `axum v0.7.9`

or the lock-file variant failed to select a version for serde. ... all possible versions conflict with previously selected packages. No code is involved yet; the resolver could not find a version of one crate that satisfies everything that asks for it.

The message names a requirement, a set of candidates that did not match, and who required it. Those three pieces usually identify the cause without further work:

  1. A candidate exists but is filtered out. Yanked versions, versions excluded by rust-version under MSRV-aware resolution, or versions absent from a private registry's index all appear as "candidate versions found which didn't match".
  2. Two requirements are incompatible. Crate A needs ^0.3.20, crate B needs =0.3.19; no single version satisfies both, and one of the two dependencies has to move.
  3. A [patch], git dependency or path override breaks the requirement. The replacement does not satisfy the version range of the crate it replaces.

The fix depends on which of the three it is, so read the candidate list first: if the version you need is listed, it is filtered; if it is not listed at all, it is a different problem.

Core Mechanics, Signatures & Reproducible Setup

Cargo unifies requirements per crate: for one semver-compatible range (major version 0.x uses minor), a single version must satisfy every dependent. Resolution order is not user-controlled, but the inputs are: Cargo.toml requirements, Cargo.lock, [patch] sections, the registry index, and the resolver version. Since Rust 1.84 the MSRV-aware resolver can deliberately skip versions whose rust-version exceeds your project's, which changes the candidate set without any file changing.

bash
cargo tree -i time # who requires time, and with which range cargo tree -d # duplicate versions in the graph cargo search time --limit 5 # what the registry exposes cargo info time # versions, yanked status, rust-version cargo update -p time --precise 0.3.19 --dry-run
toml
# Cargo.toml - the knobs that change the answer [package] name = "svc" version = "0.1.0" edition = "2024" rust-version = "1.85" # feeds MSRV-aware resolution [workspace] resolver = "3" # default for edition 2024 [dependencies] time = "0.3.20" # a direct requirement wins ties

A reproducible reproduction uses two crates with a deliberate conflict, which is the same shape as a real transitive conflict:

toml
[dependencies] serde = "=1.0.189" serde_json = "1.0" # serde_json requires serde ^1.0.194, so no version satisfies both
bash
cargo build # error: failed to select a version for the requirement `serde = "=1.0.189"` # candidate versions found which didn't match: 1.0.194, 1.0.195, ...

Key Comparison Table

Message shapeCauseFirst command
candidates found which didn't matchrange, yank or MSRV filtercargo info <crate>
no matching package namedcrate name or registry mismatchcargo search
all possible versions conflicttwo requirements cannot unifycargo tree -i <crate>
failed to load source for dependencygit URL or branch missinggit ls-remote
patch does not resolve to a versionpatch version outside the rangecheck [patch] version
package not found in registryprivate registry index stalecargo update after publishing
Resolver settingEffect on candidate setIntroduced
resolver = "1"no feature unification changesold default
resolver = "2"per-target features, edition 2021Cargo 1.51
resolver = "3"MSRV-aware selection, edition 2024Cargo 1.84
incompatible-rust-versions = "fallback"prefers compatible, falls back anywayCargo 1.84
incompatible-rust-versions = "allow"ignores rust-versionCargo 1.84

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. MSRV-aware resolution quietly removing the newest version

With resolver 3, a crate version that declares rust-version = "1.88" is skipped when your toolchain or rust-version is lower. The error then claims candidates did not match, and the newest version is simply absent:

bash
rustc --version cargo info time | grep -i rust-version # widen the filter only when the toolchain can actually build it cargo update -p time --precise 0.3.36
toml
[resolver] incompatible-rust-versions = "fallback" # in .cargo/config.toml

fallback is the pragmatic choice for applications: prefer MSRV-compatible versions, but do not fail when none exist. allow restores the old behaviour and is right for a library whose CI pins the toolchain.

2. Yanked versions

A yanked release disappears from resolution for new graphs but stays valid in an existing Cargo.lock. A fresh clone then behaves differently from a machine that has the lock:

bash
cargo info crate@1.2.3 | grep -i yanked # yanked: true cargo update -p crate --precise 1.2.4

Never delete Cargo.lock in an application to get past this; the yanked version is likely fine and the lock is the only record of the graph that shipped.

3. Git, path and patch overrides that do not satisfy the range

A [patch] entry replaces a crate only when the replacement's version satisfies the original requirement. Patching a ^0.3 requirement with a 0.4.0 fork fails with the "patch does not resolve" message:

toml
[patch.crates-io] time = { git = "https://github.com/acme/time", branch = "fix-0.3" } # the fork's Cargo.toml must still say version = "0.3.x"

A path dependency behaves the same way and is easy to get wrong in a workspace where the local crate has a bumped version.

4. Private registries and stale indexes

A crate that was published a minute ago may not be in the index the resolver reads yet, and a registry that is a sparse mirror can lag by minutes:

bash
cargo search mycrate --registry acme cargo update --registry acme

If the crate exists on crates.io but not on the configured registry, the resolver correctly reports nothing found. Check cargo config get registries before editing requirements.

5. Pinning to get unblocked, and pinning that sticks

cargo update -p <crate> --precise <version> is the right tool when a newer release breaks a build, and the resolved version stays in Cargo.lock. To communicate the constraint to the next person, add a direct dependency with the working range instead of leaving an unexplained precise pin:

toml
# keep the transitive crate at the version the rest of the graph agrees on time = "=0.3.36"

Then run cargo tree -d and confirm no duplicate major versions remain. Comparing two Cargo.lock files in Text Diff shows exactly which entry moved, which is worth doing before committing a resolution change that touches dozens of crates.

6. Features do not fix a version conflict

A missing feature (failed to select a version for a crate that exists) usually means the feature was introduced in a later version than your requirement allows. Add the feature and raise the requirement together:

toml
serde = { version = "1.0.219", features = ["derive"] }

Enabling a feature that does not exist in the resolved version produces the package does not have the feature, a different and easier error - if you see the version-selection error instead, the requirement is the thing to change.

Common Compilation/Runtime Mistakes & Version Gotchas

  • Deleting Cargo.lock in an application. It re-resolves everything, including yanked and MSRV-incompatible candidates, and the error moves around instead of disappearing.
  • cargo update as a reflex. It ignores the lock and can surface a conflict that has nothing to do with the change you were making.
  • Edition 2024 without noticing resolver 3. MSRV filtering arrives with the edition, so a dependency bump can start failing on a toolchain that was fine yesterday.
  • Assuming semver compatibility across a 0.x boundary. 0.3 and 0.4 are different crates to Cargo; two dependencies needing different 0.x majors can never unify.
  • [patch] without matching versions. The patch is ignored, or the build fails later with an unrelated-looking error.
  • A workspace member with its own Cargo.lock. Only the workspace root lock is used; a stale nested lock confuses tools and reviewers.
  • Registry mirrors that pin an old index. The crate is published and simply not visible; the message is accurate, the environment is stale.

Primary references: the Cargo resolver describes version unification and the MSRV-aware behaviour, and specifying dependencies documents requirement syntax, patches and git sources.

Official references

primary documentation

The Rust documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Rust work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Rust guides

More in Rust

All Rust guides

The guides filed next to this one in Rust, in library order.