{"record":{"id":"118fc32c5d084bc9","repo":"cross-rs/cross","slug":"cannot-make-definite-image-from-unqualified-possibleimage","errorCode":null,"errorMessage":"cannot make definite Image from unqualified PossibleImage","messagePattern":"cannot make definite Image from unqualified PossibleImage","errorType":"error_code","errorClass":"eyre::ErrReport","httpStatus":null,"severity":"error","filePath":"src/docker/image.rs","lineNumber":38,"sourceCode":"\nimpl std::fmt::Display for Image {\n    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {\n        f.write_str(&self.name)\n    }\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]\npub struct PossibleImage {\n    #[serde(rename = \"name\")]\n    pub reference: ImageReference,\n    // The toolchain triple the image is built for\n    pub toolchain: Vec<ImagePlatform>,\n}\n\nimpl PossibleImage {\n    pub fn to_definite_with(&self, engine: &Engine, msg_info: &mut MessageInfo) -> Result<Image> {\n        let ImageReference::Name(name) = self.reference.clone() else {\n            eyre::bail!(\"cannot make definite Image from unqualified PossibleImage\");\n        };\n\n        if self.toolchain.is_empty() {\n            Ok(Image {\n                name,\n                platform: ImagePlatform::DEFAULT,\n            })\n        } else {\n            let platform = if self.toolchain.len() == 1 {\n                self.toolchain.first().expect(\"should contain at least one\")\n            } else {\n                let same_arch = self\n                    .toolchain\n                    .iter()\n                    .filter(|platform| {\n                        &platform.architecture\n                            == engine.arch.as_ref().unwrap_or(&Architecture::Amd64)\n                    })","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/cross-rs/cross/blob/8c1a8aa4b661711f4b7b6ac07c2e8929ce2f7d27/src/docker/image.rs#L20-L56","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":"if !matches!(image.reference, ImageReference::Name(_)) {\n    // resolve or pull the image first\n}","typeGuard":"fn is_named(img: &PossibleImage) -> bool { matches!(img.reference, ImageReference::Name(_)) }","tryCatchPattern":null,"preventionTips":["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."],"tags":["docker","image","state","resolution"],"backgroundTag":"invalid-state-transition","analyzedSha":"8c1a8aa4b661711f4b7b6ac07c2e8929ce2f7d27","analyzedAt":"2026-09-13T15:10:43.988Z","contentChangedAt":"2026-09-13T15:10:43.988Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}