{"record":{"id":"fa431bc363cbe32b","repo":"zed-industries/zed","slug":"failed-to-resolve-font-or-any-of-the-fallback","errorCode":null,"errorMessage":"failed to resolve font '{}' or any of the fallbacks: {}","messagePattern":"failed to resolve font '(.+?)' or any of the fallbacks: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/gpui/src/text_system.rs","lineNumber":154,"sourceCode":"    }\n\n    /// Resolves the specified font, falling back to the default font stack if\n    /// the font fails to load.\n    ///\n    /// # Panics\n    ///\n    /// Panics if the font and none of the fallbacks can be resolved.\n    pub fn resolve_font(&self, font: &Font) -> FontId {\n        if let Ok(font_id) = self.font_id(font) {\n            return font_id;\n        }\n        for fallback in &self.fallback_font_stack {\n            if let Ok(font_id) = self.font_id(fallback) {\n                return font_id;\n            }\n        }\n\n        panic!(\n            \"failed to resolve font '{}' or any of the fallbacks: {}\",\n            font.family,\n            self.fallback_font_stack\n                .iter()\n                .map(|fallback| &fallback.family)\n                .join(\", \")\n        );\n    }\n\n    /// Prewarm any system font caches needed to shape text.\n    ///\n    /// This may be expensive, so callers should generally invoke it on a\n    /// background executor. Missing entries are still populated on demand by\n    /// the normal shaping path.\n    pub fn prewarm_fonts(&self, fonts: &[Font]) {\n        let mut font_ids = SmallVec::<[FontId; 8]>::new();\n        for font in fonts {\n            let font_id = self.resolve_font(font);","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/zed-industries/zed/blob/9d272b036335401f339d024ea94968fd51016c40/crates/gpui/src/text_system.rs#L136-L172","documentation":"TextSystem::resolve_font resolves a Font to a FontId by first trying the exact family, then every family in fallback_font_stack. If none of them resolve to a loaded font, it panics with the requested family and the fallback list — the API doc explicitly documents this panicking behavior. It means the requested family name does not exist in the font system and every fallback also failed.","triggerScenarios":"Rendering text with a family name that is neither installed nor bundled (typo in buffer_font_family or a theme's font), an empty/misconfigured fallback stack, or fonts failing to load at startup.","commonSituations":"`buffer_font_family`/`ui_font_family` set to a font not installed on the machine; headless or CI environments with no fonts installed; custom builds that fail to load the bundled fallback fonts.","solutions":["Set the font to one that is actually installed — verify the exact family name in Zed's font picker","Install the missing font family on the system","Ensure the fallback font stack loads at startup; in headless/CI environments install at least one font package"],"exampleFix":"// settings.json (before)\n\"buffer_font_family\": \"Fira Cod\"   // typo, not installed\n\n// after\n\"buffer_font_family\": \"Fira Code\"","handlingStrategy":"validation","validationCode":"match text_system.font_id(&font) {\n    Ok(font_id) => { /* safe to use */ }\n    Err(_) => { /* fall back to a known-good family before resolve_font panics */\n        let font = Font { family: \"Zed Plex Mono\".into(), ..font };\n        let font_id = text_system.resolve_font(&font);\n    }\n}","typeGuard":"fn font_is_resolvable(text_system: &TextSystem, family: &FontFamily) -> bool {\n    text_system.font_id(&Font { family: family.clone(), ..Default::default() }).is_ok()\n}","tryCatchPattern":null,"preventionTips":["Validate user-configured font families against all_font_names() before first render","Install at least one font package in headless/CI environments","Keep the fallback stack populated with a bundled font as the last resort"],"tags":["zed","gpui","font","text-system","panic"],"backgroundTag":"font-not-found","analyzedSha":"9d272b036335401f339d024ea94968fd51016c40","analyzedAt":"2026-08-20T19:29:52.058Z","contentChangedAt":"2026-08-20T19:29:52.058Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}