bevyengine/bevy · error · TextError

missing texture for the font atlas

Error message

missing texture for the font atlas

What it means

Raised in FontAtlas::add_glyph (crates/bevy_text/src/font_atlas.rs:104): textures.get_mut(&self.texture) returns None, i.e. the Image asset that backs the font atlas no longer exists in Assets<Image>, so the glyph cannot be copied into the atlas.

Source

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

    /// 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. Find and remove any custom code that removes Images you did not load yourself (atlas textures are created internally by bevy_text)
2. On font hot-reload, also clear the FontAtlasSet/ComputedTextBlock state so atlases (and their textures) are recreated
3. If you must evict, evict whole fonts and let text re-queue, rather than deleting individual atlas images

Example fix

// before: evicts font atlas textures too
images.clear();

// after: drop only your own images
for handle in my_images.drain(..) { images.remove(handle); }

// Before touching an atlas you manage yourself
if !images.contains(&atlas_texture_handle) {
    // texture was evicted; rebuild the atlas instead of adding glyphs
}

match atlas.add_glyph(textures, key, tex, offset, mask) {
    Err(TextError::MissingAtlasTexture) => { /* rebuild FontAtlas with a fresh Image */ }
    r => r,
}

When it happens

Trigger: Anything that deletes or replaces the atlas Image asset while the font is still in use: Assets::<Image>::remove/clear from custom cleanup code, asset hot-reload that drops the image, or manual asset-server manipulation. The very next attempt to add a glyph for that font then fails.

Common situations: 'Free VRAM' systems that clear the Image asset collection, editor tooling that recycles assets, hot-reloading a Font while cached atlases still reference the old Image handle, or mixing Bevy versions where atlas lifetimes changed.

Related errors

• missing texture atlas layout for the font
• failed to find glyph in atlas after it was added
• Each AssetId should have a corresponding asset
• Could not load texture file: {0}
• Error reading image file {path}: {error}.

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