What does cargo:crate_not_found mean?

Cargo reached the selected registry or replacement source, but that source contains no package entry matching the requested crate name.

Cargo error: no matching package named <crate> found

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

Monitor private-index publication and mirror freshness with a known-crate lookup from the same network path used by CI. Refresh vendored sources whenever reviewed changes modify `Cargo.toml` or `Cargo.lock`. Keep private registry declarations explicit so local machines and CI cannot resolve the same crate name from different sources.

Q: How can I manually validate cargo:crate_not_found?

Copy the exact crate name and `location searched` line from the full error instead of assuming the build is using crates.io. Run `cargo search --registry --limit 5` when the source supports search, or check the private registry UI for the exact normalized name. Inspect `.cargo/config.toml` for `replace-with`, `[source]`, and `[registries]` entries that can redirect lookup away from the expected registry. If vendoring is enabled, confirm the crate directory and `.cargo-checksum.json` exist in the vendor snapshot used by the failing runner.

Fix it fast

Most likely: Cargo is searching the wrong source, the crate name is wrong, or a private mirror or vendor snapshot does not contain it.

Confirm this is your error

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

error: no matching package named `internal-api` found
location searched: registry `company`
required by package `service v0.1.0`
error: no matching package named `serdee` found
location searched: crates.io index

Check the cause

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

cargo search --registry <name> <crate> --limit 5
grep -nE "^\[source\.|replace-with|^\[registries\.|^index[[:space:]]*=" .cargo/config.toml "${CARGO_HOME:-$HOME/.cargo}/config.toml" 2>/dev/null

Apply the safe fix

Use the smallest safe change that addresses the confirmed cause.

# Correct the crate name or registry in Cargo.toml.
# If vendoring is intentional, refresh it from the reviewed lockfile.
cargo vendor

Verify it works

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

cargo fetch -vv

Avoid unsafe shortcuts

Keep security and data protections in place while troubleshooting.

Do not delete Cargo.lock to solve a name lookup failure.
Do not silently switch a private dependency to crates.io.

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.

Confirm the crate name and selected source

Copy the exact crate name and location searched line from the full error instead of assuming the build is using crates.io.

Run cargo search --registry <name> <crate> --limit 5 when the source supports search, or check the private registry UI for the exact normalized name.

Inspect .cargo/config.toml for replace-with, [source], and [registries] entries that can redirect lookup away from the expected registry.

If vendoring is enabled, confirm the crate directory and .cargo-checksum.json exist in the vendor snapshot used by the failing runner.

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.

Name mismatch:correct the dependency key or use package = "<published-name>" when the local dependency name intentionally differs.

Wrong registry:add the correct registry = "<name>" to the dependency or repair the active source replacement.

Mirror lag:restore the registry synchronization path and wait until the crate metadata is visible from the failing environment.

Stale vendor source:regenerate it from the reviewed lockfile with cargo vendor and commit the corresponding config and vendor changes together.

Private dependency:confirm that every transitive private crate is present in the same registry strategy rather than silently falling back to public sources.

Why It Was Not Found

The dependency name is misspelled or uses the library import name instead of the published package name.

The dependency belongs to a private registry, but the manifest or source replacement points somewhere else.

The private index or mirror has not received the crate metadata yet, even though another environment can see it.

A vendored source is stale because the manifest or lockfile changed without refreshing the vendor directory.

Prove the Source Resolves Correctly Now

Re-run the original cargo build, cargo check, or cargo fetch in the same environment. Cargo should advance to version selection or download.

If the next error says no matching version or failed to select a version, crate-name lookup now works and the remaining problem is dependency resolution.

How Cargo looks up crate names in a source

Cargo first chooses a registry, vendored directory, or source replacement, then looks for metadata under the requested crate name. This error means name lookup failed before version selection. It is different from finding the crate but rejecting its versions, and different from a full dependency-graph conflict.

Avoid Version and Source Drift

To prevent this, monitor private-index publication and mirror freshness with a known-crate lookup from the same network path used by CI, refresh vendored sources whenever reviewed changes modify Cargo.toml or Cargo.lock, and keep private registry declarations explicit so local machines and CI cannot resolve the same crate name from different sources.

Docs and source code

Cargo Registries

Official configuration and publishing behavior for crates.io and alternative registries. - Source

Cargo installs crates and fetches dependencies from a registry.

Cargo Registry Index

Official registry index behavior for crate metadata, missing entries, authentication, and caching. - Source

The index allows a registry to have an efficient mapping from crate name to its metadata.