bevyengine/bevy · error · TextureError

only cubemaps with six faces are supported

Error message

only cubemaps with six faces are supported

What it means

TextureError::IncompleteCubemap is raised by dds_buffer_to_image (crates/bevy_image/src/dds.rs:52-63) when the DDS header's caps2 has the CUBEMAP flag but is missing at least one of the six per-face flags (CUBEMAP_POSITIVEX..CUBEMAP_NEGATIVEZ). Bevy requires exactly six faces because it uploads cubemaps as a 6-layer array; a partial cubemap would leave undefined faces. It is a strict structural check on the container, not a GPU capability issue.

Source

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

    /// 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),
        }
    }
}

/// Calculates the total number of pixels in the item.
fn pixel_count(item: Extent3d) -> usize {
    (item.width * item.height * item.depth_or_array_layers) as usize

View on GitHub (pinned to 221e52ae32)

Solutions

1. Re-export the cubemap with a tool that writes all six faces and their caps2 bits (Microsoft texconv, compressonator, cmft).
2. If only one view is needed, export a plain 2D DDS without the cubemap flag.
3. Alternatively ship the cubemap as KTX2 (toktx writes conformant cubemaps) and load that instead.
4. Verify face count after export by re-loading the file in the same tool or with a DDS inspector.

Example fix

// before — exporter wrote cubemap header with 5 faces
let image = server.load("sky.dds"); // Err(IncompleteCubemap)

// after — generate a complete cubemap with texconv
// texconv -cu -f BC7_UNORM sky.dds  (six input faces: px nx py ny pz nz)

fn on_failed(mut ev: EventReader<AssetLoadFailedEvent<Image>>) {
    for ev in ev.read() {
        if let ImageLoaderError::FileTexture(fe) = &*ev.error {
            if matches!(fe.error, TextureError::IncompleteCubemap) {
                error!("{} is a partial cubemap; re-export all six faces", fe.path);
            }
        }
    }
}

When it happens

Trigger: Loading a DDS exported as a cubemap but containing fewer than six face images — e.g. generated by stitching four faces manually, or by an exporter that omits caps2 face bits for missing faces; DDS cubemaps from older DXT tools that only set the master CUBEMAP bit.

Common situations: Skybox pipelines where one face is dropped; conversion tools (some Photoshop plugins, hand-rolled scripts) that write the cubemap flag unconditionally; replacing a face texture with a flat 2D re-export that keeps cubemap headers.

Related errors

• invalid data: {0}
• format requires transcoding: {0:?}
• Field name should exist
• Field name should be a valid tuple index
• Union types are not supported yet.

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