bevyengine/bevy · error · TextError

failed to find glyph in atlas after it was added

Error message

failed to find glyph in atlas after it was added

What it means

TextError::InconsistentAtlasState is returned at the end of add_glyph_to_atlas (crates/bevy_text/src/font_atlas.rs:186-187): the glyph was just inserted into an existing atlas or a newly pushed one, yet get_glyph_atlas_info cannot find the cache key in any atlas afterwards. It is an internal invariant break (insert claims success, lookup fails), not an expected user-error path.

Source

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

    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. Update Bevy first; check the changelog for font-atlas / glyph-cache fixes
2. Reproduce with a minimal case (one font, one size, the failing string) and file an issue
3. As a runtime workaround, reset text state (despawn and respawn the text entities, or clear and rebuild the FontAtlasSet) to force fresh atlases
4. Never ignore it silently - log the font, size, and string to identify the trigger

match add_glyph_to_atlas(...) {
    Err(TextError::InconsistentAtlasState) => {
        error!("glyph atlas cache is inconsistent; resetting text state");
        // rebuild FontAtlasSet / respawn text entities
    }
    r => r,
}

When it happens

Trigger: Effectively only reachable through a Bevy bug or corrupted FontAtlas state: cache-key mismatch between insert and lookup, another system mutating font_atlases concurrently, or state left inconsistent after prior errors (e.g. a FailedToAddGlyph path partially applied).

Common situations: Long-running apps with many fonts/sizes where atlas state drifted; custom code poking TextPipeline or FontAtlasSet internals; regressions in specific Bevy versions after refactors of the glyph cache.

Related errors

• missing texture for the font atlas
• Each AssetId should have a corresponding asset
• Fatal error when processing text: {e}.
• failed to add glyph to newly-created atlas {0:?}
• failed to get scaled glyph image for cache key: {0:?}

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