cargo: failed to select a version for the requirement `serde = "^1`" - candidate versions didn't match

TL;DR

First look at the requirement text in Cargo.toml - a malformed requirement like a missing closing quote is the most common cause of this exact failure. If the text is fine, refresh the registry index with cargo update and check whether you are offline or pinned to a stale source. The resolver is telling you the truth: with what it can see, nothing matches.

Error

"cargo: failed to select a version for the requirement `serde = "^1`"  -  candidate versions didn't match

Steps

1. Inspect the dependency line. Open Cargo.toml and read the requirement character by character. Expected: you spot whether the version string is well-formed (balanced quotes, valid semver range) - a typo here is the prime suspect.
2. Fix the requirement if it is malformed. Correct the version string to a valid requirement like serde = "1". Expected: the line parses as valid TOML with a valid version requirement.
3. Refresh the index. Run cargo update. Expected: cargo contacts the registry and updates its index; watch for network or offline-mode errors here.
4. Check for offline or vendored setups. If cargo runs with an offline flag or a vendored source replacement, it can only see cached versions. Expected: you confirm whether the build is intentionally offline and whether the cache contains the needed version.
5. Verify resolution. Run cargo build. Expected: the resolver selects a version and compilation proceeds. If it still fails, the required version may genuinely not exist - check the registry for what versions are actually published.

Use this when

• cargo fails to select a version for a requirement after an edit
• An agent hand-edited Cargo.toml and the requirement looks suspicious
• Builds work on one machine but fail on another with this error
• You suspect a stale registry index or offline mode

Not for this skill when

• The error is "failed to parse manifest" - that is a TOML syntax error, fix the syntax
• The failure is a network timeout downloading the registry - fix the network first
• The requirement is a git or path dependency - version selection does not apply

Variant phrasings

• cargo failed to select a version for the requirement
• candidate versions didn't match cargo
• cargo resolver can't find matching version after edit
• serde version requirement not matching any published version

Why it happens

Cargo resolves against the versions its index knows about. A malformed requirement string never matches anything, a stale index does not know about newly published versions, and offline mode only sees the local cache. Agents that edit Cargo.toml by string manipulation are especially prone to producing almost-valid requirements - a missing quote, a stray character - that the resolver then faithfully fails to match.

Edge cases

• Yanked versions still appear in the index but cannot be selected for new locks - if the requirement only matches yanked versions, you must move to a non-yanked one.
• A [patch] section or source replacement can hide the real registry - check .cargo/config.toml for replacements that redirect resolution.
• If the lockfile pins an old version and the requirement changed, cargo update -p [pkg] re-resolves just that package instead of everything.
• Pre-release versions never match a requirement like "1" unless the requirement opts into them - that is by design, not a bug.

Provenance

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

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

Thread query: "cargo: failed to select a version for the requirement serde = "^1" - candidate versions didn't match

TL;DR: