bevyengine/bevy · error · TextureError

transcode error: {0}

Error message

transcode error: {0}

What it means

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.

Source

Thrown at crates/bevy_image/src/image.rs:2311

    /// Transcode error.
    #[error("transcode error: {0}")]
    TranscodeError(String),
    /// Format requires transcoding.
    #[error("format requires transcoding: {0:?}")]
    FormatRequiresTranscodingError(TranscodeFormat),
    /// Only cubemaps with six faces are supported.
    #[error("only cubemaps with six faces are supported")]
    IncompleteCubemap,
}

/// The type of a raw image buffer.
#[derive(Debug)]
pub enum ImageType<'a> {
    /// The mime type of an image, for example `"image/png"`.
    MimeType(&'a str),
    /// The extension of an image file, for example `"png"`.
    Extension(&'a str),
    /// The direct format of the image
    Format(ImageFormat),
}

impl<'a> ImageType<'a> {
    /// Attempts to detect the appropriate [`ImageFormat`] for this image type.
    ///
    /// # Errors
    ///
    /// A [`TextureError`] will be returned if this image type is a MIME type or file extension for
    /// an unsupported or disabled format.
    pub fn to_image_format(&self) -> Result<ImageFormat, TextureError> {
        match self {
            ImageType::MimeType(mime_type) => ImageFormat::from_mime_type(mime_type)
                .ok_or_else(|| TextureError::InvalidImageMimeType(mime_type.to_string())),
            ImageType::Extension(extension) => ImageFormat::from_extension(extension)
                .ok_or_else(|| TextureError::InvalidImageExtension(extension.to_string())),
            ImageType::Format(format) => Ok(*format),
        }

View on GitHub (pinned to 221e52ae32)

Solutions

1. Re-encode the texture with a current basis_universal encoder (basisu CLI) — most prepare/transcode failures are encoder-version artifacts.
2. If the file is questionable, switch that asset to PNG or KTX2 and skip Basis entirely.
3. Verify the file's checksums (the loader already does in debug builds) and re-transfer the original.
4. Handle the error per-asset with a placeholder texture so one bad .basis does not abort loading.

Example fix

// before
let image = server.load("ui_atlas.basis"); // TranscodeError("Failed to transcode mip level 2 from Etc1S to Bc7Rgba: ...")

// after — re-encode with the current official encoder
// basisu -ktx2 ui_atlas.png -output_file ui_atlas.basis
let image = server.load("ui_atlas.basis");

match Image::from_buffer(&bytes, ImageType::Format(ImageFormat::Basis), formats, true, sampler, usage) {
    Err(TextureError::TranscodeError(detail)) => {
        warn!("basis transcode failed: {detail}; falling back to PNG");
        Image::from_buffer(&png_bytes, ImageType::Format(ImageFormat::Png), formats, true, sampler, usage)
    }
    result => result,
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• unsupported texture format: {0:?}
• unsupported texture format: {0}
• format requires transcoding: {0:?}
• Field name should exist
• Field name should be a valid tuple index

AI-assisted analysis of bevyengine/bevy@221e52ae32 (2026-08-20). Data as JSON: /api/errors/942cd31db2cefd15. Report an issue: GitHub.