could not determine what toolchain to use for image…

Error message

could not determine what toolchain to use for image, defaulting to `{}`

What it means

When converting an image specification to a definite image, cross tries to determine which platform/toolchain entry to use. If it cannot disambiguate, it falls back to the first platform's target and warns that it is defaulting, discarding the other candidates (the FIXME: Don't throw away comment).

Solutions

Check that the image/toolchain definition in Cross.toml names a single, explicit target so no defaulting is needed.
Set an explicit `target.<triple>.image` entry for the targets you build instead of relying on inference.
Verify the image tag follows the conventions cross expects (e.g. includes the target triple) so toolchain detection succeeds.

Example fix

# before (Cross.toml)
[build]
image = "myimage:latest"

# after
[target.aarch64-unknown-linux-gnu]
image = "myimage:aarch64-unknown-linux-gnu"

Defensive patterns

Strategy: validation

Validate before calling

// Ensure each target has an explicit image before building
for target in targets {
    assert!(config.target.get(target).and_then(|t| t.image.as_ref()).is_some(),
        "no explicit image for {}", target);
}

Prevention

Always define target.<triple>.image explicitly for custom images
Include the target triple in image tags so cross can infer the toolchain
Avoid multi-entry toolchain lists in image definitions

When it happens

Trigger: Calling to_definite_with on an Image whose toolchain/platform list has multiple entries or lacks the metadata needed to pick a target for the current host, so cross defaults to `self.toolchain.first()`.

Common situations: Custom or multi-target images defined in Cross.toml where the image name/toolchain hint does not uniquely map to a platform; images built with unusual tags cross cannot parse.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — 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/cba7c8c42116fb7d. Report an issue: GitHub.

Appendix: source

Thrown at src/docker/image.rs:78

                    // pick the platform with the same architecture
                    same_arch.first().expect("should contain one element")
                } else if let Some(platform) = same_arch
                    .iter()
                    .find(|platform| &platform.os == engine.os.as_ref().unwrap_or(&Os::Linux))
                {
                    *platform
                } else if let Some(platform) =
                    same_arch.iter().find(|platform| platform.os == Os::Linux)
                {
                    // container engine should be fine with linux
                    platform
                } else {
                    let platform = self
                        .toolchain
                        .first()
                        .expect("should be at least one platform");
                    // FIXME: Don't throw away
                    msg_info.warn(
                        format_args!("could not determine what toolchain to use for image, defaulting to `{}`", platform.target),
                    ).ok();
                    platform
                }
            };
            Ok(Image {
                platform: platform.clone(),
                name,
            })
        }
    }
}

impl<T: AsRef<str>> From<T> for PossibleImage {
    fn from(s: T) -> Self {
        PossibleImage {
            reference: s.as_ref().to_owned().into(),
            toolchain: vec![],

View on GitHub (pinned to 8c1a8aa4b6)