bevyengine/bevy · critical

Fatal error when processing text: {e}.

Error message

Fatal error when processing text: {e}.

What it means

In measure_text_system (crates/bevy_ui/src/widget/text.rs), text processing errors are triaged: font-load failures and degenerate scale factors merely retry next frame, but FailedToAddGlyph, MissingAtlasLayout, MissingAtlasTexture, and InconsistentAtlasState are considered unrecoverable and trigger panic!("Fatal error when processing text: {e}."). These mean the glyph atlas is in a state where the text can never be measured, so Bevy aborts rather than loop forever.

Source

Thrown at crates/bevy_ui/src/widget/text.rs:353

                text_flags.needs_measure_fn = false;
                text_flags.needs_recompute = true;
            }
            Err(
                TextError::NoSuchFont
                | TextError::NoSuchFontFamily(_)
                | TextError::DegenerateScaleFactor,
            ) => {
                // Try again next frame
                text_flags.needs_measure_fn = true;
            }
            Err(
                e @ (TextError::FailedToAddGlyph(_)
                | TextError::FailedToGetGlyphImage(_)
                | TextError::MissingAtlasLayout
                | TextError::MissingAtlasTexture
                | TextError::InconsistentAtlasState),
            ) => {
                panic!("Fatal error when processing text: {e}.");
            }
        };
    }
}

/// Updates the layout and size information for a UI text node on changes to the size value of its [`Node`] component,
/// or when the `needs_recompute` field of [`TextNodeFlags`] is set to true.
/// This information is computed by the [`TextPipeline`] and then stored in [`TextLayoutInfo`].
///
/// ## World Resources
///
/// [`ResMut<Assets<Image>>`](Assets<Image>) -- This system only adds new [`Image`] assets.
/// It does not modify or observe existing ones. The exception is when adding new glyphs to a [`bevy_text::FontAtlas`].
pub fn text_system(
    mut textures: ResMut<Assets<Image>>,
    mut font_atlas_set: ResMut<FontAtlasSet>,
    mut text_pipeline: ResMut<TextPipeline>,
    mut text_query: Query<(

View on GitHub (pinned to 396ca72708)

Solutions

1. Verify the font asset actually loads: check LoadState and log failures before spawning Text entities with it.
2. Fall back to a known-good font (e.g. the default FiraSans handle from the Font asset default) when a custom font fails to load.
3. Re-export or replace suspect font files (validate they open in a font editor) and confirm the byte content, not just the extension.
4. Isolate the offending Text entity by bisection (spawn subsets) to find which string/font triggers the glyph failure.
5. Update Bevy — glyph atlas handling fixes land regularly; pin to a version where your fonts render.

Example fix

// before
commands.spawn((
    Text::new("Title"),
    TextFont { font: assets.load("fonts/broken.ttf"), ..default() },
));

// after: use a font that is known to load, or the default font
commands.spawn((
    Text::new("Title"),
    TextFont { font: assets.load("fonts/FiraSans.ttf"), ..default() },
));

use bevy_asset::{AssetServer, LoadState};

// only spawn text once the font is confirmed loadable
fn spawn_text_if_font_ok(assets: &AssetServer, font: &Handle<Font>) -> Handle<Font> {
    match assets.get_load_state(font) {
        Some(LoadState::Loaded) => font.clone(),
        Some(LoadState::Failed(_)) => Handle::default(), // fall back to default font
        _ => font.clone(), // still loading: acceptable, load errors retry next frame
    }
}

// Not catchable in practice: this is a panic inside a system and aborts the app.
// Replace the strategy with prevention: validate fonts up front and fall back to
// a known-good default font when a custom font fails to load.

When it happens

Trigger: A broken, truncated, or unsupported font asset reaching the glyph rasterizer; glyph atlas textures/layouts being evicted or mutated unexpectedly; adding a glyph with malformed outline data; renderer state inconsistencies after GPU device loss.

Common situations: Loading a .ttf/.otf that is actually a renamed non-font file; using a hand-built or corrupted default font; swapping font assets at runtime while text entities reference the old handle; driver/device resets invalidating atlas textures; bugs in specific cosmic-text/bevy_text versions with certain scripts or emoji.

Related errors

• failed to add glyph to newly-created atlas {0:?}
• failed to get scaled glyph image for cache key: {0:?}
• Each AssetId should have a corresponding asset
• Fatal error when processing text: {e}.
• Failed to insert attribute. Invalid attribute format for {}.

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