{"record":{"id":"942cd31db2cefd15","repo":"bevyengine/bevy","slug":"transcode-error-0","errorCode":null,"errorMessage":"transcode error: {0}","messagePattern":"transcode error: (.+?)","errorType":"exception","errorClass":"TextureError","httpStatus":null,"severity":"error","filePath":"crates/bevy_image/src/image.rs","lineNumber":2311,"sourceCode":"    /// Transcode error.\n    #[error(\"transcode error: {0}\")]\n    TranscodeError(String),\n    /// Format requires transcoding.\n    #[error(\"format requires transcoding: {0:?}\")]\n    FormatRequiresTranscodingError(TranscodeFormat),\n    /// Only cubemaps with six faces are supported.\n    #[error(\"only cubemaps with six faces are supported\")]\n    IncompleteCubemap,\n}\n\n/// The type of a raw image buffer.\n#[derive(Debug)]\npub enum ImageType<'a> {\n    /// The mime type of an image, for example `\"image/png\"`.\n    MimeType(&'a str),\n    /// The extension of an image file, for example `\"png\"`.\n    Extension(&'a str),\n    /// The direct format of the image\n    Format(ImageFormat),\n}\n\nimpl<'a> ImageType<'a> {\n    /// Attempts to detect the appropriate [`ImageFormat`] for this image type.\n    ///\n    /// # Errors\n    ///\n    /// A [`TextureError`] will be returned if this image type is a MIME type or file extension for\n    /// an unsupported or disabled format.\n    pub fn to_image_format(&self) -> Result<ImageFormat, TextureError> {\n        match self {\n            ImageType::MimeType(mime_type) => ImageFormat::from_mime_type(mime_type)\n                .ok_or_else(|| TextureError::InvalidImageMimeType(mime_type.to_string())),\n            ImageType::Extension(extension) => ImageFormat::from_extension(extension)\n                .ok_or_else(|| TextureError::InvalidImageExtension(extension.to_string())),\n            ImageType::Format(format) => Ok(*format),\n        }","sourceCodeStart":2293,"sourceCodeEnd":2329,"githubUrl":"https://github.com/bevyengine/bevy/blob/221e52ae323febfd399bd7d067918fc43648cfb3/crates/bevy_image/src/image.rs#L2293-L2329","documentation":"TextureError::TranscodeError is raised when a compressed container needs on-load transcoding and the transcoder fails: in basis.rs:39-43 when basis_universal's prepare_transcoding rejects the file, and basis.rs:88-92 when transcode_image_level fails for a specific mip level (error text includes source basis format, target format, and level); dds.rs:116 raises it while expanding R8G8B8 data to RGBA8. It differs from InvalidData (container unparseable) and UnsupportedTextureFormat (target not allowed): here the source is valid but the conversion step itself failed.","triggerScenarios":"Loading a .basis file whose slices are internally inconsistent (transcoder state corrupted mid-file) so transcode_image_level returns an error for some mip; prepare_transcoding failing on a truncated Basis payload; a DDS RGB8 texture whose per-pixel expansion runs past the end of the level data.","commonSituations":"Basis files produced by old or patched basis_universal encoder versions; basis textures damaged in transit; mixing .basis files between encoder and transcoder versions with format drift.","solutions":["Re-encode the texture with a current basis_universal encoder (basisu CLI) — most prepare/transcode failures are encoder-version artifacts.","If the file is questionable, switch that asset to PNG or KTX2 and skip Basis entirely.","Verify the file's checksums (the loader already does in debug builds) and re-transfer the original.","Handle the error per-asset with a placeholder texture so one bad .basis does not abort loading."],"exampleFix":"// before\nlet image = server.load(\"ui_atlas.basis\"); // TranscodeError(\"Failed to transcode mip level 2 from Etc1S to Bc7Rgba: ...\")\n\n// after — re-encode with the current official encoder\n// basisu -ktx2 ui_atlas.png -output_file ui_atlas.basis\nlet image = server.load(\"ui_atlas.basis\");","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"match Image::from_buffer(&bytes, ImageType::Format(ImageFormat::Basis), formats, true, sampler, usage) {\n    Err(TextureError::TranscodeError(detail)) => {\n        warn!(\"basis transcode failed: {detail}; falling back to PNG\");\n        Image::from_buffer(&png_bytes, ImageType::Format(ImageFormat::Png), formats, true, sampler, usage)\n    }\n    result => result,\n}","preventionTips":["Pin the basis_universal encoder version used by your art pipeline and keep it in sync with the runtime.","Validate .basis files with the encoder's own verifier before committing.","Keep a PNG fallback for critical UI textures."],"tags":["bevy","basis-universal","transcode","compressed-formats","rust"],"backgroundTag":"texture-transcode-failed","analyzedSha":"221e52ae323febfd399bd7d067918fc43648cfb3","analyzedAt":"2026-08-20T16:12:39.808Z","contentChangedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T20:17:18.057Z"}