What does cargo:version_not_found mean?

Cargo found the crate in the selected source, but none of the visible versions satisfy the version requirement being resolved.

Cargo error: no matching version found for package <crate>

Q: How do I prevent cargo:version_not_found in CI?

Test private crate publication and index visibility before releasing dependent services. Run controlled dependency updates in CI so yanks and mirror lag are discovered outside urgent builds. Pin the Rust toolchain and source configuration used to create reviewed lockfiles.

Q: How can I manually validate cargo:version_not_found?

Capture the complete resolver block with `cargo check -vv` and note the requested range, candidate versions, and `location searched` line. Inspect the direct requirement in `Cargo.toml` and the existing package entry in `Cargo.lock` without editing either file. Check the registry UI or index for the desired version and confirm whether it is published, yanked, or still missing from a private mirror. When only CI fails, compare `cargo -Vv`, source replacement, and the committed lockfile against the working local environment.

Fix it fast

Most likely: The requirement asks for a version the selected registry cannot currently offer.

Confirm this is your error

Match the output and confirm you are troubleshooting the same failure.

error: failed to select a version for the requirement `internal-api = "^2.4"`
candidate versions found which did not match: 2.3.1, 2.3.0
location searched: registry `company`
error: no matching version `^1.8` found for package `example-crate`

Check the cause

Run focused checks to identify what is failing in this environment.

cargo check -vv
# Run outside a workspace if you do not want Cargo to create Cargo.lock.
cargo info --registry <name> <crate>@<version>
cargo tree -i <crate>

Apply the safe fix

Use the smallest safe change that addresses the confirmed cause.

# After confirming the version exists and is intended
cargo update -p <crate> --precise <version>

Verify it works

Repeat the relevant checks and confirm the original error is gone.

cargo check --locked
cargo test --locked

What Cargo Could Not Find

The request was valid enough to perform a lookup, but the upstream source could not match it to a real package, image, version, or artifact for this environment.

Compare the requirement with available versions

Capture the complete resolver block with cargo check -vv and note the requested range, candidate versions, and location searched line.

Inspect the direct requirement in Cargo.toml and the existing package entry in Cargo.lock without editing either file.

Check the registry UI or index for the desired version and confirm whether it is published, yanked, or still missing from a private mirror.

When only CI fails, compare cargo -Vv, source replacement, and the committed lockfile against the working local environment.

Confirm the exact package you asked for

Before you retry, confirm the exact name, version or tag, namespace, and index or registry this environment is supposed to use. Most fixes here are about pointing at the right thing.

Bad requirement:correct the semver range to the narrowest range that genuinely matches the API your code supports.

Missing release:publish the required private crate version first, or choose a version already available in the intended registry.

Yanked release:move to a non-yanked compatible version and review why the release was yanked before overriding anything.

Stale private index:repair or refresh the registry mirror rather than manually rewriting source entries in Cargo.lock

Lockfile drift:use cargo update -p <crate> --precise <version> only after confirming that exact version exists and the update is intended.

Why It Was Not Found

The version requirement is mistyped, overly narrow, or asks for a release that was never published.

The only matching release was yanked and is not already locked or explicitly selected under Cargo rules.

A private registry or proxy index is stale and exposes older candidate versions than the authoritative source.

Local and CI builds use different lockfiles, Cargo versions, registry protocols, or replacement sources.

Prove the Source Resolves Correctly Now

Repeat the original command with the same registry and lockfile. Cargo should select a concrete version and proceed to fetch or graph resolution.

Review the resulting Cargo.lock diff when a version changed, then run the project tests before committing the update.

How Cargo filters visible crate versions

After locating a crate, Cargo filters its published versions by the manifest requirement, yanked state, lockfile preference, requested features, and other resolver rules. This error occurs before a build begins. The useful clues are the exact requirement, candidate versions, registry source, and whether a private index is current.

Avoid Version and Source Drift

To prevent this, test private crate publication and index visibility before releasing dependent services, run controlled dependency updates in CI so yanks and mirror lag are discovered outside urgent builds, and pin the Rust toolchain and source configuration used to create reviewed lockfiles.

Docs and source code

Cargo Dependency Resolution

Official explanation of version selection, lockfiles, yanked releases, features, and resolver conflicts. - Source

This process is called dependency resolution and is performed by the resolver.

Specifying Dependencies

Official manifest syntax for registry, path, git, and workspace dependencies. - Source

Cargo supports several ways to specify the location of a dependency.

cargo info

Official command for inspecting one exact package version from a selected registry. - Source

This command displays information about a package.