cross-rs/cross · error

git tag does not match package version.

Error message

git tag does not match package version.

What it means

determine_image_name computes the docker image tags for a release build. When the build is triggered from a git tag starting with 'v', it strips the prefix and requires the tag version to exactly equal the package version; on mismatch it bails. This guards against publishing an image whose tag and embedded version disagree.

Solutions

  1. Align the git tag and package version: update Cargo.toml to match the tag (or retag to match the version) before building
  2. Retag the release: e.g. `git tag -f v0.5.0 && git push -f origin v0.5.0` after fixing the version file
  3. If this is not a versioned release, build from a non-v-prefixed branch/commit so the tag check is skipped

Example fix

// before
git tag v1.2.3   # but Cargo.toml: version = "1.2.2"
// after
# Cargo.toml: version = "1.2.3"  (commit)
git tag v1.2.3 && git push origin v1.2.3
Defensive patterns

Strategy: validation

Validate before calling

// in CI, before the docker build job
VERSION=$(grep -m1 '^version' Cargo.toml | sed 's/.*"\(.*\)"/\1/')
TAG=${GITHUB_REF_NAME#v}
if [[ "$GITHUB_REF_TYPE" == "tag" && "$GITHUB_REF_NAME" == v* && "$VERSION" != "$TAG" ]]; then
  echo "git tag v$TAG does not match package version $VERSION"; exit 1;
fi

Try / catch

match build_docker_image(...) {
    Ok(name) => push(name),
    Err(e) if e.to_string().contains("git tag does not match package version") => {
        eprintln!("Release aborted: align Cargo.toml version with the v-prefixed git tag, then re-tag");
        std::process::exit(1);
    }
    Err(e) => return Err(e),
}

Prevention

When it happens

Trigger: A git ref of type 'tag' named `v<something>` is present, and `<something>` (after stripping 'v') is not string-equal to the crate's package version.

Common situations: Tagging v1.2.3 while Cargo.toml still says 1.2.2 (or vice versa) after a version bump was forgotten; tagging with a suffix like v1.2.3-rc1 not reflected in the version; re-running the release workflow against an old tag after bumping the version.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

AI-assisted analysis of cross-rs/cross@8c1a8aa4b6 (2026-09-13). Data as JSON: /api/errors/7370ed2f8af8d37a. Report an issue: GitHub.

Appendix: source

Thrown at xtask/src/build_docker_image.rs:409

    })
}

pub fn determine_image_name(
    target: &ImageTarget,
    repository: &str,
    ref_type: &str,
    ref_name: &str,
    is_latest: bool,
    version: &str,
) -> cross::Result<Vec<String>> {
    let mut tags = vec![];
    match (ref_type, ref_name) {
        ("tag", ref_name) if ref_name.starts_with('v') => {
            let tag_version = ref_name
                .strip_prefix('v')
                .expect("tag name should start with v");
            if version != tag_version {
                eyre::bail!("git tag does not match package version.")
            }
            tags.push(target.image_name(repository, version));
            // Check for unstable releases, tag stable releases as `latest`
            if is_latest {
                tags.push(target.image_name(repository, "latest"))
            }
        }
        ("branch", ref_name) => {
            if let Some(gh_queue) = ref_name.strip_prefix("gh-readonly-queue/") {
                let (_, source) = gh_queue
                    .split_once('/')
                    .ok_or_else(|| eyre::eyre!("invalid gh-readonly-queue branch name"))?;
                tags.push(target.image_name(repository, source));
            } else {
                tags.push(target.image_name(repository, ref_name));
            }

            if ["staging", "trying"]

View on GitHub (pinned to 8c1a8aa4b6)