unable to find native dockerfile named

Error message

unable to find native dockerfile named {dockerfile_name} for target {target}.

What it means

In build_docker_image, when a target is built with a native (non-cross) toolchain, the task derives the dockerfile name as `Dockerfile.native` or `Dockerfile.native.` (from target.sub), joins it with docker_root, and requires the file to exist. If it does not, the task bails with this error naming the exact expected filename and target.

Solutions

Create the expected `Dockerfile.native` (or `Dockerfile.native.`) in docker_root
Verify the target's `sub` field matches an existing Dockerfile.native. filename, or unset the sub
Confirm docker_root points at the directory containing the native dockerfiles in your checkout

Example fix

// before
target.sub = Some("musl") // no Dockerfile.native.musl exists
// after
add docker/Dockerfile.native.musl // or run with a sub that has a dockerfile

Defensive patterns

Strategy: validation

Validate before calling

use std::path::Path;
fn native_dockerfile_exists(docker_root: &Path, sub: Option<&str>) -> bool {
    let name = match sub {
        Some(s) => format!("Dockerfile.native.{s}"),
        None => "Dockerfile.native".to_owned(),
    };
    docker_root.join(name).exists()
}
// check before invoking xtask
assert!(native_dockerfile_exists(&docker_root, target.sub.as_deref()));

Try / catch

let out = build_docker_image(target, ...);
if let Err(e) = out {
    if e.to_string().contains("unable to find native dockerfile") {
        eprintln!("Missing native dockerfile for {} - add it or drop the sub target", target);
    } else { return Err(e); }
}

Prevention

Add Dockerfile.native. together with any new target sub variant
Keep Dockerfile.native present as the default fallback in docker_root
Verify the target's sub name against existing filenames before running the build
List `ls docker/Dockerfile.native*` in CI before the build step to fail fast with a clear message

When it happens

Trigger: target.sub is Some(sub) producing Dockerfile.native., or None producing Dockerfile.native, and docker_root does not contain that file (checked with .exists()).

Common situations: Building a native target whose `sub` variant has no dedicated Dockerfile.native. yet; a checkout missing the native dockerfiles; configuring a target sub-name that doesn't match any file; docker_root misconfigured to the wrong directory.

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/5c910746d4ea630d. Report an issue: GitHub.

Appendix: source

Thrown at xtask/src/build_docker_image.rs:211

        docker_build.current_dir(&docker_root);

        let docker_platform = platform.docker_platform();
        let mut dockerfile = dockerfile.clone();
        docker_build.args(["--platform", &docker_platform]);
        let uppercase_triple = target.name.to_ascii_uppercase().replace('-', "_");
        docker_build.args([
            "--build-arg",
            &format!("CROSS_TARGET_TRIPLE={}", uppercase_triple),
        ]);
        // add our platform, and determine if we need to use a native docker image
        if has_native_image(docker_platform.as_str(), target, msg_info)? {
            let dockerfile_name = match target.sub.as_deref() {
                Some(sub) => format!("Dockerfile.native.{sub}"),
                None => "Dockerfile.native".to_owned(),
            };
            let dockerfile_path = docker_root.join(&dockerfile_name);
            if !dockerfile_path.exists() {
                eyre::bail!(
                    "unable to find native dockerfile named {dockerfile_name} for target {target}."
                );
            }
            dockerfile = dockerfile_path.to_utf8()?.to_string();
        }

        if push {
            docker_build.arg("--push");
        } else if engine.kind.supports_output_flag() && no_output {
            docker_build.args(["--output", "type=tar,dest=/dev/null"]);
        } else if no_output {
            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![];

View on GitHub (pinned to 8c1a8aa4b6)