bevyengine/bevy · error · TextError

scale factor <= 0

Error message

scale factor <= 0

What it means

TextPipeline checks scale_factor <= 0.0 up front (crates/bevy_text/src/pipeline.rs:81-84), warns once ('Text scale factor is <= 0.0. No text will be displayed.') and returns TextError::DegenerateScaleFactor. Text layout and rendering are skipped entirely: a non-positive scale factor cannot map logical to physical pixels.

Source

Thrown at crates/bevy_text/src/error.rs:29

    /// that the font failed to load for some other reason
    #[error("No such font family {0:?}")]
    NoSuchFontFamily(String),
    /// Failed to add glyph to a newly created atlas for some reason
    #[error("failed to add glyph to newly-created atlas {0:?}")]
    FailedToAddGlyph(u16),
    /// Failed to get scaled glyph image for cache key
    #[error("failed to get scaled glyph image for cache key: {0:?}")]
    FailedToGetGlyphImage(u16),
    /// Missing texture atlas layout for the font
    #[error("missing texture atlas layout for the font")]
    MissingAtlasLayout,
    /// Missing texture for the font atlas
    #[error("missing texture for the font atlas")]
    MissingAtlasTexture,
    /// Failed to find glyph in atlas after it was added
    #[error("failed to find glyph in atlas after it was added")]
    InconsistentAtlasState,
    #[error("scale factor <= 0")]
    /// Text cannot be rendered for a scale factor <= zero.
    DegenerateScaleFactor,
}

View on GitHub (pinned to 396ca72708)

Solutions

  1. Clamp the scale factor to a positive minimum before use: scale.max(f32::EPSILON) or a sane floor like 0.1
  2. Skip text updates while the window is minimized or its size is 0
  3. Check your UiScale resource and any tween/animation that drives it for zero crossings
  4. Handle the error variant to fall back to the previous frame's layout instead of failing the system

Example fix

// before
let scale = window.width() / reference_width; // 0.0 when minimized

// after
let scale = (window.width() / reference_width).max(0.1);
Defensive patterns

Strategy: validation

Validate before calling

// Run before any text pipeline call
fn safe_scale_factor(scale_factor: f32) -> f32 {
    if scale_factor > 0.0 { scale_factor } else { 1.0 }
}

Try / catch

match pipeline.compose_or_queue(&mut font_atlas_sets, ..., scale_factor, ...) {
    Err(TextError::DegenerateScaleFactor) => { /* keep last frame's layout */ }
    r => r,
}

Prevention

When it happens

Trigger: Passing a zero or negative scale factor into text composition/queueing: a UiScale resource set to 0, a scale factor computed from a zero-sized window (minimized or not yet resized), or custom code calling the pipeline with an unvalidated factor.

Common situations: Setting UiScale(0.0) to 'hide' UI (breaks all text instead), platforms reporting scale 0 during window setup/minimize, division by a zero window dimension when deriving scale, or animating scale through 0 without clamping.

Related errors

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