{"record":{"id":"d2ce0eebe9decf64","repo":"bevyengine/bevy","slug":"failed-to-add-glyph-to-newly-created-atlas-0","errorCode":null,"errorMessage":"failed to add glyph to newly-created atlas {0:?}","messagePattern":"failed to add glyph to newly-created atlas (.+?)","errorType":"exception","errorClass":"TextError","httpStatus":null,"severity":"error","filePath":"crates/bevy_text/src/error.rs","lineNumber":15,"sourceCode":"use thiserror::Error;\n\n#[derive(Debug, PartialEq, Eq, Error)]\n/// Errors related to the textsystem\npub enum TextError {\n    /// Font was not found, this could be that the font has not yet been loaded, or\n    /// that the font failed to load for some other reason\n    #[error(\"font not found\")]\n    NoSuchFont,\n    /// Font was not found, this could be that the font has not yet been loaded, or\n    /// that the font failed to load for some other reason\n    #[error(\"No such font family {0:?}\")]\n    NoSuchFontFamily(String),\n    /// Failed to add glyph to a newly created atlas for some reason\n    #[error(\"failed to add glyph to newly-created atlas {0:?}\")]\n    FailedToAddGlyph(u16),\n    /// Failed to get scaled glyph image for cache key\n    #[error(\"failed to get scaled glyph image for cache key: {0:?}\")]\n    FailedToGetGlyphImage(u16),\n    /// Missing texture atlas layout for the font\n    #[error(\"missing texture atlas layout for the font\")]\n    MissingAtlasLayout,\n    /// Missing texture for the font atlas\n    #[error(\"missing texture for the font atlas\")]\n    MissingAtlasTexture,\n    /// Failed to find glyph in atlas after it was added\n    #[error(\"failed to find glyph in atlas after it was added\")]\n    InconsistentAtlasState,\n    #[error(\"scale factor <= 0\")]\n    /// Text cannot be rendered for a scale factor <= zero.\n    DegenerateScaleFactor,\n}\n","sourceCodeStart":1,"sourceCodeEnd":33,"githubUrl":"https://github.com/bevyengine/bevy/blob/396ca727080776bd313bb892423b7d94e03b81b4/crates/bevy_text/src/error.rs#L1-L33","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the font size that triggered it; cap FontSize/font_size to something sane (e.g. <= 1024px) and re-test","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","If the glyph is legitimately larger than your device max texture size, render at a smaller size or split the content","If sizes look reasonable, update Bevy (font atlas sizing fixes land regularly) and file an issue with the font file, size, and glyph id"],"exampleFix":"// before\ncommands.spawn((\n    Text::new(\"Big\"),\n    TextFont { font_size: 4000.0, ..default() },\n));\n\n// after\ncommands.spawn((\n    Text::new(\"Big\"),\n    TextFont { font_size: 512.0, ..default() },\n));","handlingStrategy":"try-catch","validationCode":"// Cap font sizes before spawning text so glyphs stay placeable\nfn clamp_font_size(size: f32) -> f32 {\n    size.clamp(1.0, 1024.0)\n}","typeGuard":null,"tryCatchPattern":"match add_glyph_to_atlas(&mut font_atlases, textures, scaler, smoothing, glyph_id) {\n    Ok(info) => { /* use info */ }\n    Err(TextError::FailedToAddGlyph(gid)) => {\n        warn_once!(\"glyph {gid} does not fit any atlas; check font size\");\n        // skip glyph, keep rendering the rest\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Keep TextFont font_size values in a sane range (tens/hundreds of px)","Smoke-test every shipped font at the largest size you use","Log glyph id + font size when the error fires so the trigger is identifiable"],"tags":["rust","bevy","text","glyph","texture-atlas","font"],"backgroundTag":"texture-atlas-full","analyzedSha":"396ca727080776bd313bb892423b7d94e03b81b4","analyzedAt":"2026-08-20T16:12:39.808Z","contentChangedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-09-09T01:17:15.007Z"}