zed-industries/zed · error

failed to resolve font '{}' or any of the fallbacks: {}

Error message

failed to resolve font '{}' or any of the fallbacks: {}

What it means

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.

Source

Thrown at crates/gpui/src/text_system.rs:154

    }

    /// Resolves the specified font, falling back to the default font stack if
    /// the font fails to load.
    ///
    /// # Panics
    ///
    /// Panics if the font and none of the fallbacks can be resolved.
    pub fn resolve_font(&self, font: &Font) -> FontId {
        if let Ok(font_id) = self.font_id(font) {
            return font_id;
        }
        for fallback in &self.fallback_font_stack {
            if let Ok(font_id) = self.font_id(fallback) {
                return font_id;
            }
        }

        panic!(
            "failed to resolve font '{}' or any of the fallbacks: {}",
            font.family,
            self.fallback_font_stack
                .iter()
                .map(|fallback| &fallback.family)
                .join(", ")
        );
    }

    /// Prewarm any system font caches needed to shape text.
    ///
    /// This may be expensive, so callers should generally invoke it on a
    /// background executor. Missing entries are still populated on demand by
    /// the normal shaping path.
    pub fn prewarm_fonts(&self, fonts: &[Font]) {
        let mut font_ids = SmallVec::<[FontId; 8]>::new();
        for font in fonts {
            let font_id = self.resolve_font(font);

View on GitHub (pinned to 9d272b0363)

Solutions

1. Set the font to one that is actually installed — verify the exact family name in Zed's font picker
2. Install the missing font family on the system
3. Ensure the fallback font stack loads at startup; in headless/CI environments install at least one font package

Example fix

// settings.json (before)
"buffer_font_family": "Fira Cod"   // typo, not installed

// after
"buffer_font_family": "Fira Code"

match text_system.font_id(&font) {
    Ok(font_id) => { /* safe to use */ }
    Err(_) => { /* fall back to a known-good family before resolve_font panics */
        let font = Font { family: "Zed Plex Mono".into(), ..font };
        let font_id = text_system.resolve_font(&font);
    }
}

fn font_is_resolvable(text_system: &TextSystem, family: &FontFamily) -> bool {
    text_system.font_id(&Font { family: family.clone(), ..Default::default() }).is_ok()
}

When it happens

Trigger: 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.

Common situations: `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.

Related errors

• blocking sender returned without value
• Expected to render a table row
• compute_indents_fn is required for UniformListDecoration
• wl_seat below required version: {} < {}
• wl_output below required version: {} < {}

AI-assisted analysis of zed-industries/zed@9d272b0363 (2026-08-20). Data as JSON: /api/errors/fa431bc363cbe32b. Report an issue: GitHub.