# 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

```text
"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