cross-rs/cross · error · eyre::ErrReport

cannot make definite Image from unqualified PossibleImage

Error message

cannot make definite Image from unqualified PossibleImage

What it means

`PossibleImage::to_definite_with` converts a possibly-unqualified image reference into a concrete `Image`. It can only do so when the reference is `ImageReference::Name`; a `PossibleImage` holding an unresolved/unqualified reference (e.g. a locally-built or hash-based image) cannot be turned into a definite image and fails.

Solutions

Resolve the PossibleImage to a named ImageReference (pull/tag the image) before calling to_definite_with.
Configure an explicit toolchain image name in the cross config for the target.
Use the engine's image lookup/resolution API to convert the reference first.

Defensive patterns

Strategy: type-guard

Validate before calling

if !matches!(image.reference, ImageReference::Name(_)) {
    // resolve or pull the image first
}

Type guard

fn is_named(img: &PossibleImage) -> bool { matches!(img.reference, ImageReference::Name(_)) }

Prevention

Always run image resolution (pull/tag) before converting PossibleImage to Image.
Configure explicit toolchain image names for custom targets.
Add a debug assertion that reference is Name in code paths requiring definite images.

When it happens

Trigger: Calling `to_definite_with` on a `PossibleImage` whose `reference` is not `ImageReference::Name` — i.e. the image was never resolved to a registry-qualified name before this point.

Common situations: Using a custom-built toolchain image that was never pulled/tagged, a code path that skips image resolution, or misconfigured target toolchain image settings in cross config.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

Thrown at src/docker/image.rs:38

impl std::fmt::Display for Image {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.name)
    }
}

#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
pub struct PossibleImage {
    #[serde(rename = "name")]
    pub reference: ImageReference,
    // The toolchain triple the image is built for
    pub toolchain: Vec<ImagePlatform>,
}

impl PossibleImage {
    pub fn to_definite_with(&self, engine: &Engine, msg_info: &mut MessageInfo) -> Result<Image> {
        let ImageReference::Name(name) = self.reference.clone() else {
            eyre::bail!("cannot make definite Image from unqualified PossibleImage");
        };

        if self.toolchain.is_empty() {
            Ok(Image {
                name,
                platform: ImagePlatform::DEFAULT,
            })
        } else {
            let platform = if self.toolchain.len() == 1 {
                self.toolchain.first().expect("should contain at least one")
            } else {
                let same_arch = self
                    .toolchain
                    .iter()
                    .filter(|platform| {
                        &platform.architecture
                            == engine.arch.as_ref().unwrap_or(&Architecture::Amd64)
                    })

View on GitHub (pinned to 8c1a8aa4b6)