{"record":{"id":"2209ac5671af3b74","repo":"bevyengine/bevy","slug":"only-cubemaps-with-six-faces-are-supported","errorCode":null,"errorMessage":"only cubemaps with six faces are supported","messagePattern":"only cubemaps with six faces are supported","errorType":"exception","errorClass":"TextureError","httpStatus":null,"severity":"error","filePath":"crates/bevy_image/src/image.rs","lineNumber":2317,"sourceCode":"    /// 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        }\n    }\n}\n\n/// Calculates the total number of pixels in the item.\nfn pixel_count(item: Extent3d) -> usize {\n    (item.width * item.height * item.depth_or_array_layers) as usize","sourceCodeStart":2299,"sourceCodeEnd":2335,"githubUrl":"https://github.com/bevyengine/bevy/blob/221e52ae323febfd399bd7d067918fc43648cfb3/crates/bevy_image/src/image.rs#L2299-L2335","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-export the cubemap with a tool that writes all six faces and their caps2 bits (Microsoft texconv, compressonator, cmft).","If only one view is needed, export a plain 2D DDS without the cubemap flag.","Alternatively ship the cubemap as KTX2 (toktx writes conformant cubemaps) and load that instead.","Verify face count after export by re-loading the file in the same tool or with a DDS inspector."],"exampleFix":"// before — exporter wrote cubemap header with 5 faces\nlet image = server.load(\"sky.dds\"); // Err(IncompleteCubemap)\n\n// after — generate a complete cubemap with texconv\n// texconv -cu -f BC7_UNORM sky.dds  (six input faces: px nx py ny pz nz)","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"fn on_failed(mut ev: EventReader<AssetLoadFailedEvent<Image>>) {\n    for ev in ev.read() {\n        if let ImageLoaderError::FileTexture(fe) = &*ev.error {\n            if matches!(fe.error, TextureError::IncompleteCubemap) {\n                error!(\"{} is a partial cubemap; re-export all six faces\", fe.path);\n            }\n        }\n    }\n}","preventionTips":["Generate skybox DDS cubemaps with texconv/cmft and re-load them in the same tool to verify six faces.","Prefer KTX2 for cubemaps when the toolchain allows it.","Include every cubemap asset in the CI load test."],"tags":["bevy","dds","cubemap","skybox","rust"],"backgroundTag":"incomplete-cubemap","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"}