What causes "unable to find dockerfile for target "{target}"" in cross-rs/cross?

Create the missing file `Dockerfile. ` in docker_root (or cross_toolchain_root)

unable to find dockerfile for target

Error message

unable to find dockerfile for target "{target}"

What it means

locate_dockerfile resolves the Dockerfile for a cross-compilation target. It looks for `Dockerfile.<target>` first in the cross-toolchain root, then in the docker root; if the file exists in neither location it bails with this error. It is thrown because the target has no corresponding dockerfile checked into either expected directory.

Solutions

Create the missing file `Dockerfile.<target>` in docker_root (or cross_toolchain_root)
Verify the target triple spelling matches an existing Dockerfile.<target> filename
Check that cross_toolchain_root/docker_root point at the directories that actually contain the dockerfiles (CI checkout depth/path config)
List files named Dockerfile.* in the repo and pick a target that exists

Example fix

// before
xtask build-docker-image --target aarch64-unknow-linux-gnu
// after
xtask build-docker-image --target aarch64-unknown-linux-gnu // matches Dockerfile.aarch64-unknown-linux-gnu

Defensive patterns

Strategy: validation

Validate before calling

use std::path::Path;
fn dockerfile_exists(cross_root: &Path, docker_root: &Path, target: &str) -> bool {
    let name = format!("Dockerfile.{target}");
    cross_root.join(&name).exists() || docker_root.join(&name).exists()
}
// check before invoking xtask
assert!(dockerfile_exists(&cross_root, &docker_root, &target), "missing Dockerfile for {target}");

Try / catch

let out = build_docker_image(target, ...);
if let Err(e) = out {
    if e.to_string().contains("unable to find dockerfile") {
        eprintln!("No Dockerfile.{target} in cross_toolchain_root or docker_root; add one or fix the target triple");
    } else { return Err(e); }
}

Prevention

Keep one Dockerfile.<target> per target in the build matrix and add it in the same PR that adds the target
Verify target triples against rustc's target list (`rustc --print target-list`)
Include the docker directory in your repo checkout/CI checkout settings
Add a test iterating the target matrix and asserting each Dockerfile exists

When it happens

Trigger: The target name passed to build_docker_image has no `Dockerfile.<target>` file in either `cross_toolchain_root` or `docker_root` (checked via .exists()).

Common situations: Adding a new target to the build matrix without creating its Dockerfile.<target>; a typo in the target triple (e.g. 'aarch64-unknow-linux-gnu'); renaming/moving the docker directory so the lookup path is wrong; running the xtask on a partially cloned repo.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at xtask/src/build_docker_image.rs:96

    #[clap(long, short = 'a', action = clap::builder::ArgAction::Append)]
    pub platform: Vec<ImagePlatform>,
    /// Targets to build for
    #[clap()]
    pub targets: Vec<ImageTarget>,
}

fn locate_dockerfile(
    target: ImageTarget,
    docker_root: &Path,
    cross_toolchain_root: &Path,
) -> cross::Result<(ImageTarget, String)> {
    let dockerfile_name = format!("Dockerfile.{target}");
    let dockerfile_root = if cross_toolchain_root.join(&dockerfile_name).exists() {
        &cross_toolchain_root
    } else if docker_root.join(&dockerfile_name).exists() {
        &docker_root
    } else {
        eyre::bail!("unable to find dockerfile for target \"{target}\"");
    };
    let dockerfile = dockerfile_root.join(dockerfile_name).to_utf8()?.to_string();
    Ok((target, dockerfile))
}

pub fn build_docker_image(
    BuildDockerImage {
        ref_type,
        ref_name,
        build_opts,
        is_latest,
        tag: tag_override,
        repository,
        labels,
        dry_run,
        force,
        push,
        no_output,

View on GitHub (pinned to 8c1a8aa4b6)