{"record":{"id":"232bb33febd3706e","repo":"sxyazi/yazi","slug":"unknown-image-format","errorCode":null,"errorMessage":"unknown image format","messagePattern":"unknown image format","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"yazi-binding/src/image.rs","lineNumber":22,"sourceCode":"use mlua::{MetaMethod, UserData, UserDataFields, UserDataMethods};\n\n// --- ImageInfo\n#[derive(Clone, Copy)]\npub struct ImageInfo {\n\tformat:      image::ImageFormat,\n\twidth:       u32,\n\theight:      u32,\n\tcolor:       image::ColorType,\n\torientation: Option<image::metadata::Orientation>,\n}\n\nimpl ImageInfo {\n\tpub async fn new(path: PathBuf) -> image::ImageResult<Self> {\n\t\ttokio::task::spawn_blocking(move || {\n\t\t\tlet reader = image::ImageReader::open(path)?.with_guessed_format()?;\n\n\t\t\tlet Some(format) = reader.format() else {\n\t\t\t\treturn Err(ImageError::IoError(std::io::Error::new(\n\t\t\t\t\tstd::io::ErrorKind::InvalidData,\n\t\t\t\t\t\"unknown image format\",\n\t\t\t\t)));\n\t\t\t};\n\n\t\t\tlet mut decoder = reader.into_decoder()?;\n\t\t\tlet (width, height) = decoder.dimensions();\n\t\t\tOk(Self {\n\t\t\t\tformat,\n\t\t\t\twidth,\n\t\t\t\theight,\n\t\t\t\tcolor: decoder.color_type(),\n\t\t\t\torientation: decoder.orientation().ok(),\n\t\t\t})\n\t\t})\n\t\t.await\n\t\t.map_err(|e| ImageError::IoError(e.into()))?\n\t}","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/sxyazi/yazi/blob/5f901b886b14de1f17460b6e52e9de5d67f8aba9/yazi-binding/src/image.rs#L4-L40","documentation":"ImageInfo::new opens an image file with image::ImageReader::open and with_guessed_format; if the format cannot be determined (reader.format() returns None), the code wraps the failure into an IoError with InvalidData and the message \"unknown image format\". This means the file could be opened but its magic bytes/content don't match any decoder enabled in the image crate's feature set.","triggerScenarios":"Calling ImageInfo::new(path) on a file whose contents don't match a supported format: corrupt/truncated images, text or binary files with an image extension, or formats the image crate was compiled without (feature-gated decoders like webp/avif/heic).","commonSituations":"A previewer or plugin passes a user-supplied file to ImageInfo without checking the extension/magic bytes; a file is renamed to .png but isn't a PNG; the image crate features were trimmed so a valid image has no decoder; empty or zero-byte files.","solutions":["Check the file is actually an image before calling ImageInfo::new (read magic bytes or match the extension against known image formats).","Enable the required decoder features of the `image` crate (e.g. webp, avif, jpeg, png) in Cargo.toml so with_guessed_format can identify the format.","Verify the file is not truncated or corrupted (compare size/checksum against the source); re-download or regenerate it.","Handle the error gracefully and fall back to a generic file preview instead of an image preview."],"exampleFix":"// before\nlet info = ImageInfo::new(path).await?;\n// after\nlet info = match ImageInfo::new(path).await {\n    Ok(info) => info,\n    Err(_) => return Ok(FilePreview::Generic), // not an image (or unsupported format)\n};","handlingStrategy":"fallback","validationCode":"// Rust\nasync fn is_probably_image(path: &Path) -> bool {\n    let magic = |bytes: &[u8]| match bytes {\n        [0x89, b'P', b'N', b'G', ..] | [0xFF, 0xD8, 0xFF, ..] | b\"GIF8\"[..].iter().copied().collect::<Vec<_>>().as_slice() if bytes.starts_with(b\"GIF8\") => true,\n        [b'B', b'M', ..] | [b'R', b'I', b'F', b'F', ..] => true,\n        _ => false,\n    };\n    tokio::fs::read(path).await.map(|b| b.len() > 11 && magic(&b)).unwrap_or(false)\n}","typeGuard":null,"tryCatchPattern":"match ImageInfo::new(path).await {\n    Ok(info) => render(info),\n    Err(e) if e.to_string().contains(\"unknown image format\") => show_generic_preview(),\n    Err(e) => return Err(e.into()),\n}","preventionTips":["Sniff magic bytes before treating a file as an image.","Keep image crate decoder features enabled for the formats you expect.","Never trust file extensions alone.","Always provide a generic fallback preview."],"tags":["image","format-detection","io","invalid-data"],"backgroundTag":"unknown-image-format","analyzedSha":"5f901b886b14de1f17460b6e52e9de5d67f8aba9","analyzedAt":"2026-09-02T18:38:25.566Z","contentChangedAt":"2026-09-02T18:38:25.566Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}