patch ` ` version mismatch note: patch location contains …

Error message

patch `{}` version mismatch
note: patch location contains {}, but patch definition requires `{}`
help: check patch location `{}`
help: check `{}` patch definition for `{}` in `{}`

What it means

The patch source contains the named package, but its version does not satisfy the `version_req` declared in the patch entry. The registry formats `found` (available versions) versus the required version and bails in the `else` branch at registry.rs:1051. Cargo refuses to apply a patch whose version is incompatible with the requirement.

Solutions

Update the patch's `version` requirement to match what the source actually provides.
Tag/checkout the source at a version satisfying the requirement.
Loosen the requirement (e.g. `version = "2.0"`) if the newer version is acceptable.

Example fix

# before
[patch.crates-io]
foo = { version = "1.0", git = "https://example.com/foo-fork" }
# fork is at 2.0.0

# after
[patch.crates-io]
foo = { version = "2.0", git = "https://example.com/foo-fork" }

Defensive patterns

Strategy: validation

Validate before calling

fn patch_version_satisfies(available: &[semver::Version], req: &semver::VersionReq) -> bool {
    available.iter().any(|v| req.matches(v))
}
// compare the patch source's published versions against the patch's version_req

Prevention

Keep the patch's `version` requirement aligned with the source's actual version.
Bump the requirement when the fork releases a new major.
Use `cargo update` after changing patch versions to refresh resolution.

When it happens

Trigger: `[patch.crates-io] foo = { version = "1.0", git = "..." }` but the git repo's `foo` is at `2.0.0`, which does not satisfy `^1.0`.

Common situations: Fork drifted to a newer major version while the patch still requires the old one. Forgetting to bump the patch's `version` after the fork releases a new major. Version requirement copied from the original dependency that no longer matches the fork.

Related errors

AI-assisted analysis of rust-lang/cargo@98a09e7e7d (2026-08-11). Data as JSON: /api/errors/7ace46dd933665e3. Report an issue: GitHub.

Appendix: source

Thrown at src/workspace/registry.rs:1072

        1 => format!("version `{}`", vers[0]),
        _ => {
            vers.sort();
            let strs: Vec<_> = vers.into_iter().map(|v| v.to_string()).collect();
            format!("versions `{}`", strs.join(", "))
        }
    };
    Err(if found.is_empty() {
        anyhow::anyhow!(
            "patch location `{}` does not contain packages matching `{}`\n\
            help: check `{}` patch definition for `{}` in `{}`",
            &original_patch.dep.source_id(),
            &original_patch.dep.package_name(),
            &original_patch.dep.package_name(),
            orig_patch_url,
            original_patch.loc
        )
    } else {
        anyhow::anyhow!(
            "patch `{}` version mismatch\n\
            note: patch location contains {}, but patch definition requires `{}`\n\
            help: check patch location `{}`\n\
            help: check `{}` patch definition for `{}` in `{}`",
            &original_patch.dep.package_name(),
            found,
            &original_patch.dep.version_req(),
            &original_patch.dep.source_id(),
            &original_patch.dep.package_name(),
            orig_patch_url,
            original_patch.loc
        )
    })
}

View on GitHub (pinned to 98a09e7e7d)