{"id":"5cb513c5da637e0c","repo":"rust-lang/cargo","slug":"the-replacement-specification-matched-multipl","errorCode":null,"errorMessage":"the replacement specification `{}` matched multiple packages:\n  * {}\n{}","messagePattern":"the replacement specification `(.+?)` matched multiple packages:\n  \\* (.+?)\n(.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"src/resolver/dep_cache.rs","lineNumber":143,"sourceCode":"                    _ => None,\n                });\n            let s = summaries.next().ok_or_else(|| {\n                anyhow::format_err!(\n                    \"no matching package for override `{}` found\\n\\\n                     location searched: {}\\n\\\n                     version required: {}\",\n                    spec,\n                    dep.source_id(),\n                    dep.version_req()\n                )\n            })?;\n            let summaries = summaries.collect::<Vec<_>>();\n            if !summaries.is_empty() {\n                let bullets = summaries\n                    .iter()\n                    .map(|s| format!(\"  * {}\", s.package_id()))\n                    .collect::<Vec<_>>();\n                return Err(anyhow::anyhow!(\n                    \"the replacement specification `{}` matched \\\n                     multiple packages:\\n  * {}\\n{}\",\n                    spec,\n                    s.package_id(),\n                    bullets.join(\"\\n\")\n                ));\n            }\n\n            assert_eq!(\n                s.name(),\n                summary.name(),\n                \"dependency should be hard coded to have the same name\"\n            );\n            if s.version() != summary.version() {\n                return Err(anyhow::anyhow!(\n                    \"replacement specification `{}` matched {} and tried to override it with {}\\n\\\n                     avoid matching unrelated packages by being more specific\",\n                    spec,","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/rust-lang/cargo/blob/0e07a155371a6ce88ae53a2c00df940280c09a67/src/resolver/dep_cache.rs#L125-L161","documentation":"Raised in `dep_cache.rs` while processing `[replace]` (the legacy `[replace]` table) override specs. A single replacement spec resolved to two or more distinct candidate packages in the registry (same name requirement, multiple matching versions returned by `query_vec`). Cargo requires a `[replace]` spec to match exactly one package version so the substitution is unambiguous; more than one means it cannot decide which to substitute.","triggerScenarios":"Using `[replace]` in `Cargo.toml` with a version requirement broad enough to match multiple published versions of the override target, e.g. `[replace] \"serde:1.0.0\" = { path = \"../my-serde\" }` where the registry query returns several 1.0.x versions that all satisfy the replacement dependency's version req. The first candidate plus remaining `summaries` being non-empty triggers the bail.","commonSituations":"Migrating from `[replace]` to `[patch]` incorrectly; broad version wildcards (`*`, `^1`) on replacement dependency specs; replacement target crates that publish many versions fitting the req. `[replace]` is deprecated, so this surfaces mostly in older configs.","solutions":["Pin the replacement dependency to an exact version in the `[replace]` entry so only one package matches.","Switch from `[replace]` to the supported `[patch]` table, which handles multi-version matching differently.","Make the replace spec's version requirement more specific (e.g. `=1.0.184` instead of `^1.0`)."],"exampleFix":"# before\n[replace]\n\"serde:1.0.0\" = { path = \"../my-serde\" }\n# after\n[patch.crates-io]\nserde = { path = \"../my-serde\" }","handlingStrategy":"validation","validationCode":"# In CI, lint Cargo.toml to forbid [replace] (use [patch] instead):\nif grep -nq '^\\[replace\\]' Cargo.toml; then\n  echo 'ERROR: [replace] is deprecated and error-prone; use [patch]'; exit 1;\nfi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer `[patch]` over the deprecated `[replace]` table.","Pin replacement dependency versions exactly (`=x.y.z`) so only one package matches.","Run `cargo check` after editing replacement specs to catch multi-match errors early."],"tags":["replace","dependency-resolution","config","deprecated"],"analyzedSha":"0e07a155371a6ce88ae53a2c00df940280c09a67","analyzedAt":"2026-08-06T01:46:58.334Z","schemaVersion":2}