{"record":{"id":"93d3abed95f8b0fd","repo":"bevyengine/bevy","slug":"failed-to-calculate-aspect-ratio-for-cluster-scre","errorCode":null,"errorMessage":"Failed to calculate aspect ratio for Cluster: screen dimensions must be positive, non-zero values","messagePattern":"Failed to calculate aspect ratio for Cluster: screen dimensions must be positive, non-zero values","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/bevy_light/src/cluster/mod.rs","lineNumber":320,"sourceCode":"            total: 4096,\n            z_slices: 24,\n            z_config: ClusterZConfig::default(),\n            dynamic_resizing: true,\n        }\n    }\n}\n\nimpl ClusterConfig {\n    fn dimensions_for_screen_size(&self, screen_size: UVec2) -> UVec3 {\n        match &self {\n            ClusterConfig::None => UVec3::ZERO,\n            ClusterConfig::Single => UVec3::ONE,\n            ClusterConfig::XYZ { dimensions, .. } => *dimensions,\n            ClusterConfig::FixedZ {\n                total, z_slices, ..\n            } => {\n                let aspect_ratio: f32 = AspectRatio::try_from_pixels(screen_size.x, screen_size.y)\n                    .expect(\"Failed to calculate aspect ratio for Cluster: screen dimensions must be positive, non-zero values\")\n                    .ratio();\n                let mut z_slices = *z_slices;\n                if *total < z_slices {\n                    warn!(\"ClusterConfig has more z-slices than total clusters!\");\n                    z_slices = *total;\n                }\n                let per_layer = *total as f32 / z_slices as f32;\n\n                let y = f32::sqrt(per_layer / aspect_ratio);\n\n                let mut x = (y * aspect_ratio) as u32;\n                let mut y = y as u32;\n\n                // check extremes\n                if x == 0 {\n                    x = 1;\n                    y = per_layer as u32;\n                }","sourceCodeStart":302,"sourceCodeEnd":338,"githubUrl":"https://github.com/bevyengine/bevy/blob/4805ca792c3e94eef07afd6fa9a2712f388c9a67/crates/bevy_light/src/cluster/mod.rs#L302-L338","documentation":"bevy_light's ClusterConfig::FixedZ::dimensions_for_screen_size builds an AspectRatio from the render target size and .expect()s it (crates/bevy_light/src/cluster/mod.rs:318). A zero width or height makes AspectRatio::try_from_pixels fail with AspectRatioError::Zero, and the expect turns that into this panic during light clustering.","triggerScenarios":"Forward-clustered lighting (ClusterConfig::FixedZ) running while a camera's screen/target size is (0, 0) — a minimized window, a zero-sized surface during resize or recreation, or a camera targeting a zero-sized image.","commonSituations":"Minimizing the window during play; WMs that briefly resize to zero during tiling transitions; secondary cameras on not-yet-sized render targets; headless or surface-recreation paths.","solutions":["Prevent zero-sized windows/camera targets (clamp resizes, pause rendering while minimized).","Use ClusterConfig::None or ClusterConfig::Single for cameras whose targets may legitimately be zero-sized.","Update Bevy — zero-size clustering handling has been patched across releases, so a newer minor may already contain the fix."],"exampleFix":"// before: minimized window (0x0) + ClusterConfig::FixedZ -> panic in light clustering\n\n// after: guard zero-size frames in your camera/window update logic\nlet size = window.physical_size();\nif size.x == 0 || size.y == 0 {\n    return; // skip work while there is no drawable area\n}","handlingStrategy":"validation","validationCode":"use bevy_window::Window;\n\nfn screen_size_valid(window: &Window) -> bool {\n    window.physical_size().x > 0 && window.physical_size().y > 0\n}\n\n// in systems that create/resize cameras or react to window changes:\nif !screen_size_valid(&window) {\n    return; // skip frame: zero-size target would panic FixedZ clustering\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pause rendering work while the window is minimized or zero-sized.","Prefer ClusterConfig::None or Single for cameras with optional targets.","Test the minimized-window path in CI for clustered-lighting projects.","Keep Bevy current — zero-size clustering panics have been fixed over patch releases."],"tags":["bevy","rendering","lighting","cluster","panic","window-size","aspect-ratio"],"backgroundTag":"zero-size-render-target","analyzedSha":"4805ca792c3e94eef07afd6fa9a2712f388c9a67","analyzedAt":"2026-08-20T16:12:39.808Z","contentChangedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}