{"record":{"id":"4ab72f13411250e0","repo":"bevyengine/bevy","slug":"image-data-is-not-initialized","errorCode":null,"errorMessage":"image data is not initialized","messagePattern":"image data is not initialized","errorType":"exception","errorClass":"TextureAccessError","httpStatus":null,"severity":"error","filePath":"crates/bevy_image/src/image.rs","lineNumber":2279,"sourceCode":"    /// how to retain it if necessary.\n    #[error(\"image data is not initialized\")]\n    Uninitialized,\n    /// The texture's dimension was different than indicated by the accessor used.\n    #[error(\"attempt to access texture with different dimension\")]\n    WrongDimension,\n}\n\n/// An error that occurs when loading a texture.\n#[derive(Error, Debug)]\npub enum TextureError {\n    /// Image MIME type is invalid.\n    #[error(\"invalid image mime type: {0}\")]\n    InvalidImageMimeType(String),\n    /// Image extension is invalid.\n    #[error(\"invalid image extension: {0}\")]\n    InvalidImageExtension(String),\n    /// Failed to load an image.\n    #[error(\"failed to load an image: {0}\")]\n    ImageError(#[from] image::ImageError),\n    /// Texture format isn't supported.\n    #[error(\"unsupported texture format: {0}\")]\n    UnsupportedTextureFormat(String),\n    /// Supercompression isn't supported.\n    #[error(\"supercompression not supported: {0}\")]\n    SuperCompressionNotSupported(String),\n    /// Failed to decompress an image.\n    #[error(\"failed to decompress an image: {0}\")]\n    SuperDecompressionError(String),\n    /// Invalid data.\n    #[error(\"invalid data: {0}\")]\n    InvalidData(String),\n    /// Transcode error.\n    #[error(\"transcode error: {0}\")]\n    TranscodeError(String),\n    /// Format requires transcoding.\n    #[error(\"format requires transcoding: {0:?}\")]","sourceCodeStart":2261,"sourceCodeEnd":2297,"githubUrl":"https://github.com/bevyengine/bevy/blob/221e52ae323febfd399bd7d067918fc43648cfb3/crates/bevy_image/src/image.rs#L2261-L2297","documentation":"TextureAccessError::Uninitialized is returned by Image::pixel_bytes and Image::pixel_bytes_mut (crates/bevy_image/src/image.rs:1702, 1714) when the Image's data field (pub data: Option<Vec<u8>>) is None. That means there is no CPU-side copy: either the image was created with Image::new_uninit and never filled, or it was loaded with RenderAssetUsages::RENDER_WORLD so Bevy dropped the CPU bytes after uploading to the GPU. The variant's doc comment points to RenderAssetUsages for controlling when data is moved.","triggerScenarios":"Calling pixel_bytes/pixel_bytes_mut (or the get_color_at*/set_color_at* accessors built on them) on an Image whose data is None — created via Image::new_uninit without a subsequent write, or loaded through ImageLoaderSettings with asset_usage = RenderAssetUsages::RENDER_WORLD (CPU copy freed after GPU upload).","commonSituations":"Games that set RENDER_WORLD-only usage to halve texture memory, then later try to read pixels for screenshots, picking, or serialization; images created with new_uninit awaiting an async fill; code that assumes texture data is always resident on CPU after load.","solutions":["Load the asset with the default RenderAssetUsages::MAIN_WORLD | RenderAssetUsages::RENDER_WORLD so the CPU copy survives the GPU upload.","If you used Image::new_uninit, fill it first (Image::new, Image::new_fill, or a write via pixel_bytes_mut) before any read.","If the handle already points at a RENDER_WORLD-only asset, re-load the source file from the AssetServer or keep a second MAIN_WORLD copy reserved for CPU reads."],"exampleFix":"// before — CPU data is dropped after upload\nserver.load_with_settings(\"tex.png\", |s: &mut ImageLoaderSettings| {\n    s.asset_usage = RenderAssetUsages::RENDER_WORLD;\n});\nlet bytes = image.pixel_bytes(UVec3::ZERO)?; // Err(Uninitialized)\n\n// after — retain the CPU copy\ns.asset_usage = RenderAssetUsages::MAIN_WORLD | RenderAssetUsages::RENDER_WORLD;","handlingStrategy":"validation","validationCode":"// before pixel_bytes / pixel_bytes_mut / get_color_at:\nif image.data.as_ref().is_some_and(|d| !d.is_empty()) {\n    let bytes = image.pixel_bytes(UVec3::new(x, y, 0))?;\n}","typeGuard":"fn has_cpu_data(image: &Image) -> bool {\n    image.data.as_ref().is_some_and(|d| !d.is_empty())\n}","tryCatchPattern":"match image.pixel_bytes(coords) {\n    Ok(bytes) => { /* ... */ }\n    Err(TextureAccessError::Uninitialized) => {\n        // re-load with MAIN_WORLD usage or keep a CPU copy\n    }\n    Err(e) => warn!(\"pixel access failed: {e}\"),\n}","preventionTips":["Keep RenderAssetUsages::MAIN_WORLD in asset_usage for any texture you will read or serialize.","Only use RenderAssetUsages::RENDER_WORLD alone for pure GPU assets you never touch on CPU.","Fill new_uninit images with new_fill or pixel writes before reading them."],"tags":["bevy","texture","render-asset-usages","uninitialized","rust"],"backgroundTag":"cpu-texture-data-unavailable","analyzedSha":"221e52ae323febfd399bd7d067918fc43648cfb3","analyzedAt":"2026-08-20T16:12:39.808Z","contentChangedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-09-09T01:17:15.007Z"}