cross-rs/cross · error

Refusing to push without tag or branch. Specify a…

Error message

Refusing to push without tag or branch. Specify a repository and tag with `--repository <repository> --tag <tag>`

What it means

The `build_docker_image` xtask refuses to push a Docker image when the build was triggered from a ref that is neither a tag nor a branch AND an explicit `--tag` override was not supplied. Pushing from such a ref would produce an ambiguous/unintended image tag, so it panics as a safety check.

Solutions

1. Pass an explicit `--repository <repository> --tag <tag>` to the xtask invocation.
2. Run the build from a proper tag or branch ref so the release-tagging path is selected.
3. If this is a local test build, drop the push flag so the image is only tagged `local`.

Example fix

// before
cargo xtask build-docker-image --push  # on detached HEAD
// after
cargo xtask build-docker-image --push --repository myrepo --tag v1.2.3

if push && tag_override.is_none() && !is_tag_or_branch_ref(ref_name) {
    return Err("refusing to push: supply --repository/--tag or run from a tag/branch");
}

When it happens

Trigger: Running the xtask with `push = true` while `ref_name` matches none of the tag/branch release cases and neither `--tag` (tag_override) nor a recognizable branch/tag ref is provided — e.g. building/pushing from a detached HEAD, a PR ref, or an arbitrary commit.

Common situations: CI pipelines that trigger on merge queues or detached checkouts, manually running the xtask locally with a push flag enabled, or pushing from a commit SHA ref without specifying repository/tag.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• unexpected progress type: expected plain, auto, or tty and…
• no valid choice to pick for image name
• most common base image is
• pr should be a number, got
• cannot make definite Image from unqualified PossibleImage

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

Appendix: source

Thrown at xtask/src/build_docker_image.rs:241

            msg_info.fatal("cannot specify `--no-output` with engine that does not support the `--output` flag", 1);
        } else if has_buildkit {
            docker_build.arg("--load");
        }

        let mut tags = vec![];

        match (ref_type.as_deref(), ref_name.as_deref()) {
            (Some(ref_type), Some(ref_name)) => tags.extend(determine_image_name(
                target,
                &repository,
                ref_type,
                ref_name,
                is_latest,
                &version,
            )?),
            _ => {
                if push && tag_override.is_none() {
                    panic!(
                        "Refusing to push without tag or branch. Specify a repository and tag with `--repository <repository> --tag <tag>`"
                    )
                }
                tags.push(target.image_name(&repository, "local"));
            }
        }

        if let Some(ref tag) = tag_override {
            tags = vec![target.image_name(&repository, tag)];
        }

        if engine.kind.supports_pull_flag() {
            docker_build.arg("--pull");
        }
        let base_name = format!("{repository}/{}", target.name);
        if no_cache {
            docker_build.arg("--no-cache");
        } else if engine.kind.supports_cache_from_type() {

View on GitHub (pinned to 8c1a8aa4b6)