bevyengine/bevy · error · TextError

failed to add glyph to newly-created atlas {0:?}

Error message

failed to add glyph to newly-created atlas {0:?}

What it means

Returned by FontAtlas::add_glyph (reached via add_glyph_to_atlas in crates/bevy_text/src/font_atlas.rs) when DynamicTextureAtlasBuilder::add_texture rejects the glyph image. Bevy first tries every existing atlas for the font, then builds a brand-new atlas sized to the glyph (smallest power-of-two >= 512px that fits glyph + padding); the error means even that freshly created atlas could not accept the texture, and neither atlas texture nor layout was modified.

Source

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

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. Check the font size that triggered it; cap FontSize/font_size to something sane (e.g. <= 1024px) and re-test
  2. Inspect the font file with a font tool (fonttools, ftxdumf or a viewer) to confirm the failing glyph rasterizes at that size; try a different font
  3. If the glyph is legitimately larger than your device max texture size, render at a smaller size or split the content
  4. If sizes look reasonable, update Bevy (font atlas sizing fixes land regularly) and file an issue with the font file, size, and glyph id

Example fix

// before
commands.spawn((
    Text::new("Big"),
    TextFont { font_size: 4000.0, ..default() },
));

// after
commands.spawn((
    Text::new("Big"),
    TextFont { font_size: 512.0, ..default() },
));
Defensive patterns

Strategy: try-catch

Validate before calling

// Cap font sizes before spawning text so glyphs stay placeable
fn clamp_font_size(size: f32) -> f32 {
    size.clamp(1.0, 1024.0)
}

Try / catch

match add_glyph_to_atlas(&mut font_atlases, textures, scaler, smoothing, glyph_id) {
    Ok(info) => { /* use info */ }
    Err(TextError::FailedToAddGlyph(gid)) => {
        warn_once!("glyph {gid} does not fit any atlas; check font size");
        // skip glyph, keep rendering the rest
    }
    Err(e) => return Err(e),
}

Prevention

When it happens

Trigger: Queueing text for rendering where a glyph's rasterized dimensions cannot be placed: font sizes so large the glyph exceeds the maximum texture size, zero-sized or malformed glyph images produced by the rasterizer, or color/emoji bitmap strikes that the atlas builder refuses. The u16 payload is the glyph id (key.glyph_id) that failed.

Common situations: Extreme TextFont::font_size values (thousands of pixels), color emoji fonts (CBDT/sbix strikes) at large sizes, GPU max-texture-dimension limits making glyph+padding unplaceable, or long-lived sessions where corrupted atlas state makes valid glyphs fail. Rarely, a Bevy/swash regression.

Related errors

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