bevyengine/bevy · error · TextError

failed to get scaled glyph image for cache key: {0:?}

Error message

failed to get scaled glyph image for cache key: {0:?}

What it means

Produced in get_outlined_glyph_texture (crates/bevy_text/src/font_atlas.rs:207): swash's Render (trying ColorOutline, ColorBitmap, then Outline sources) returns None when asked to render the given glyph id, so Bevy has no image to put in the atlas. It means the scaler/font combination produced no renderable image for that glyph index.

Source

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

use thiserror::Error;

#[derive(Debug, PartialEq, Eq, Error)]
/// Errors related to the textsystem
pub enum TextError {
    /// Font was not found, this could be that the font has not yet been loaded, or
    /// that the font failed to load for some other reason
    #[error("font not found")]
    NoSuchFont,
    /// Font was not found, this could be that the font has not yet been loaded, or
    /// 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. Test the font in another renderer to confirm the character renders; if not, use a complete font
  2. Re-subset or regenerate the font so all needed glyphs (including .notdef) have outlines
  3. Update Bevy so its swash dependency picks up rasterizer fixes
  4. Match on TextError::FailedToGetGlyphImage and skip/log the glyph instead of aborting the whole text update

Example fix

// before: broken font silently breaks every frame
match font_atlas.add_glyph_to_atlas(...) { ... }

// after: degrade gracefully per glyph
match add_glyph_to_atlas(&mut font_atlases, textures, scaler, smoothing, glyph_id) {
    Ok(info) => atlas_info = Some(info),
    Err(TextError::FailedToGetGlyphImage(gid)) => {
        warn_once!("font lacks a renderable glyph {gid}");
        continue;
    }
    Err(e) => return Err(e),
}
Defensive patterns

Strategy: try-catch

Try / catch

match add_glyph_to_atlas(&mut font_atlases, textures, scaler, smoothing, glyph_id) {
    Ok(info) => atlas_info = Some(info),
    Err(TextError::FailedToGetGlyphImage(gid)) => {
        warn_once!("glyph {gid} has no renderable image in this font");
        continue;
    }
    Err(e) => return Err(e),
}

Prevention

When it happens

Trigger: Calling text queueing/shaping where the resolved glyph id has no outline or bitmap in the selected font: broken fonts whose .notdef is unrenderable, bitmap-only fonts missing a strike at the requested size, or glyph ids that don't match the font actually used (font substitution/index drift).

Common situations: Using a stripped-down or subsetted font that lost glyphs, emoji/bitmap fonts without suitable strikes, variable font instancing quirks, or an old swash version bundled with an older Bevy. Also seen after hand-editing font files.

Related errors

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