What causes "AspectRatio error: width or height is zero" in bevyengine/bevy?

Guard the call: only construct the AspectRatio when both dimensions are greater than 0.

bevyengine/bevy · error · AspectRatioError

AspectRatio error: width or height is zero

Error message

AspectRatio error: width or height is zero

What it means

AspectRatio::try_new / try_from_pixels / TryFrom<Vec2> reject inputs where width or height is exactly 0.0, because the resulting ratio would be zero or require division by zero (crates/bevy_math/src/aspect_ratio.rs:38). try_from_pixels(u32, u32) with either dimension 0 is the most common producer.

Source

Thrown at crates/bevy_math/src/aspect_ratio.rs:95

    pub const fn is_square(&self) -> bool {
        self.0 == 1.0
    }
}

impl TryFrom<Vec2> for AspectRatio {
    type Error = AspectRatioError;

    #[inline]
    fn try_from(value: Vec2) -> Result<Self, Self::Error> {
        Self::try_new(value.x, value.y)
    }
}

/// An Error type for when [`AspectRatio`](`super::AspectRatio`) is provided invalid width or height values
#[derive(Error, Debug, PartialEq, Eq, Clone, Copy)]
pub enum AspectRatioError {
    /// Error due to width or height having zero as a value.
    #[error("AspectRatio error: width or height is zero")]
    Zero,
    /// Error due towidth or height being infinite.
    #[error("AspectRatio error: width or height is infinite")]
    Infinite,
    /// Error due to width or height being Not a Number (NaN).
    #[error("AspectRatio error: width or height is NaN")]
    NaN,
}

View on GitHub (pinned to 396ca72708)

Solutions

Guard the call: only construct the AspectRatio when both dimensions are greater than 0.
Fall back to a known ratio (e.g. AspectRatio::SIXTEEN_NINE) when measurements are zero-sized.
Skip work that depends on aspect ratio for zero-sized render targets.

Example fix

// before
let ar = AspectRatio::try_from_pixels(size.x, size.y).unwrap(); // panics when minimized

// after
let ar = match AspectRatio::try_from_pixels(size.x, size.y) {
    Ok(ar) => ar,
    Err(_) => AspectRatio::SIXTEEN_NINE,
};

Defensive patterns

Strategy: validation

Validate before calling

use bevy_math::AspectRatio;

fn valid_dimensions(w: f32, h: f32) -> bool {
    w != 0.0 && h != 0.0
}

let ar = if valid_dimensions(w, h) {
    AspectRatio::try_new(w, h).ok()
} else {
    None // skip or fall back to a known ratio
};

Try / catch

match AspectRatio::try_from_pixels(size.x, size.y) {
    Ok(ar) => { /* use ar.ratio() */ }
    Err(AspectRatioError::Zero) => { /* skip zero-sized frames */ }
    Err(e) => warn!("bad aspect ratio inputs: {e}"),
}

Prevention

Never construct aspect ratios from unmeasured or zero-sized dimensions.
Gate render-target-dependent math on width > 0 && height > 0.
Use a known fallback ratio for degenerate frames instead of unwrapping.

When it happens

Trigger: Constructing an AspectRatio from a Vec2::ZERO, from pixel dimensions where either is 0 (minimized window, unresized surface), or from an unmeasured layout value that defaulted to zero.

Common situations: Minimized windows on first frames; cameras with unset or zero-sized targets; uninitialized dimension fields; downstream panics such as bevy_light's ClusterConfig::FixedZ expect on try_from_pixels.

Related errors

AI-assisted analysis of bevyengine/bevy@396ca72708 (2026-08-20). Data as JSON: /api/errors/f1818d730ddacee3. Report an issue: GitHub.