rust-lang/cargo · error · anyhow::Error

replacement specification `{}` matched {} and tried to overr

Error message

replacement specification `{}` matched {} and tried to override it with {}
avoid matching unrelated packages by being more specific

What it means

Emitted in `dep_cache.rs` after a replacement matched: the matched override package `s` has a different version than the `summary` being replaced. The assertion ensures name equality, then explicitly rejects version mismatch because `[replace]` semantics expect the override to stand in for the same version. Substituting a different version would silently change the dependency graph.

Source

Thrown at src/resolver/dep_cache.rs:158

                    .iter()
                    .map(|s| format!("  * {}", s.package_id()))
                    .collect::<Vec<_>>();
                return Err(anyhow::anyhow!(
                    "the replacement specification `{}` matched \
                     multiple packages:\n  * {}\n{}",
                    spec,
                    s.package_id(),
                    bullets.join("\n")
                ));
            }

            assert_eq!(
                s.name(),
                summary.name(),
                "dependency should be hard coded to have the same name"
            );
            if s.version() != summary.version() {
                return Err(anyhow::anyhow!(
                    "replacement specification `{}` matched {} and tried to override it with {}\n\
                     avoid matching unrelated packages by being more specific",
                    spec,
                    summary.version(),
                    s.version(),
                ));
            }

            let replace = if s.source_id() == summary.source_id() {
                debug!("Preventing\n{:?}\nfrom replacing\n{:?}", summary, s);
                None
            } else {
                Some(s)
            };
            let matched_spec = spec.clone();

            // Make sure no duplicates
            if let Some((spec, _)) = potential_matches.next() {

View on GitHub (pinned to 0e07a15537)

Solutions

Align the replacement package's version with the original (bump the replaced package's version in its `Cargo.toml` to match, or pin both sides to the same version).
Use `[patch]` instead of `[replace]` if you intend to substitute a different version of a dependency.
Make the replacement spec more specific so it cannot accidentally match a differently-versioned package.

Example fix

# before
[replace]
"foo:1.2.3" = { git = "https://example/foo-fork" }  # fork is at 1.2.4
# after
# edit fork's Cargo.toml to version = "1.2.3", OR:
[patch.crates-io]
foo = { git = "https://example/foo-fork" }

Defensive patterns

Strategy: validation

Validate before calling

# Ensure replace target version == replaced version before committing:
# edit the fork's Cargo.toml so `version = ` matches the left-hand side of [replace].
grep -n 'version' fork-crate/Cargo.toml

Prevention

Keep replacement fork versions synchronized with the originals.
Use `[patch]` when you need version flexibility in overrides.
Add a CI step that runs `cargo check` on any `[replace]`/`[patch]` change.

When it happens

Trigger: A `[replace]` spec's target dependency (the right-hand side) resolves to a version different from the package on the left being replaced — e.g. replacing `foo:1.2.3` but the replacement source publishes `foo` at `1.2.4`. The `s.version() != summary.version()` branch fires.

Common situations: Replacement source (path/git fork) was updated and re-published at a new version after the `[replace]` entry was written; mismatched version req in the replacement dependency declaration; using `[replace]` where you actually want a version bump (which `[replace]` forbids by design).

Related errors

AI-assisted analysis of rust-lang/cargo@0e07a15537 (2026-08-06). Data as JSON: /data/errors/bb992b54c7908785.json. Report an issue: GitHub.