query piet font family returned None for font family

Error message

query piet font family returned None for font family '{font_family}

What it means

When converting TextAttributes to piet attributes, a FontFamily attribute must be resolvable by the piet text backend (font_family()). If the backend has no font registered under that family name, it returns None and this error is thrown. It means the requested font family is not installed or not known to the font config system.

Solutions

Install the missing font family on the system (or bundle it with the app)
Fall back to a default font family when piet's font_family() returns None instead of failing
Validate font availability (font-kit / fontconfig query) when loading text content and substitute missing families
Check for exact-name mismatches — query fontconfig with `fc-list` and use the canonical family string

Example fix

// before
piet_text.font_family(font_family.as_str())
    .map(piet::TextAttribute::FontFamily)
    .ok_or_else(|| anyhow!("query piet font family returned None..."))?
// after
let family = piet_text.font_family(font_family.as_str())
    .unwrap_or(piet_text.font_family(DEFAULT_FAMILY)?);
Ok(piet::TextAttribute::FontFamily(family))

Defensive patterns

Strategy: fallback

Validate before calling

let available: Vec<String> = fontdb_query_families(); // or fc-list output
let family = if available.iter().any(|f| f == requested_family) { requested_family } else { DEFAULT_FAMILY.to_string() };

Type guard

fn font_available(piet_text: &impl piet::Text, family: &str) -> bool {
    piet_text.font_family(family).is_some()
}

Try / catch

match stroke.try_into_piet_attrs(piet_text) {
    Ok(attrs) => attrs,
    Err(e) if e.to_string().contains("font family returned None") => {
        log::warn!("font missing, using default: {e}");
        attrs_with_default_family()
    }
    Err(e) => return Err(e),
}

Prevention

Always fall back to a known-installed default family instead of propagating the error
Substitute missing fonts at document load time and persist the substitution
Bundle common fonts with the app for consistent cross-platform rendering
Check `fc-list` coverage on headless/CI environments before text rendering tests

When it happens

Trigger: Rendering a text stroke whose TextAttribute::FontFamily names a font not present on the system — e.g. after importing a document using a platform-specific or custom font, or a typo in the family name.

Common situations: Opening a .rnote file created on another machine with different fonts; headless Linux systems with minimal fontconfig; family names that differ between platforms (e.g. 'Helvetica' vs 'Arial').

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of flxzt/rnote@bbc5354502 (2026-09-08). Data as JSON: /api/errors/bc8efc9b99cf7c35. Report an issue: GitHub.

Appendix: source

Thrown at crates/rnote-engine/src/strokes/textstroke.rs:139

            piet::TextAttribute::TextColor(color) => Self::TextColor(Color::from(color)),
            piet::TextAttribute::Style(font_style) => Self::Style(font_style.into()),
            piet::TextAttribute::Underline(underline) => Self::Underline(underline),
            piet::TextAttribute::Strikethrough(strikethrough) => Self::Strikethrough(strikethrough),
        }
    }
}

impl TextAttribute {
    pub fn try_into_piet<T>(self, piet_text: &mut T) -> anyhow::Result<piet::TextAttribute>
    where
        T: piet::Text,
    {
        match self {
            TextAttribute::FontFamily(font_family) => piet_text
                .font_family(font_family.as_str())
                .map(piet::TextAttribute::FontFamily)
                .ok_or_else(|| {
                    anyhow::anyhow!(
                        "query piet font family returned None for font family '{font_family}"
                    )
                }),
            TextAttribute::FontSize(font_size) => Ok(piet::TextAttribute::FontSize(font_size)),
            TextAttribute::FontWeight(font_weight) => Ok(piet::TextAttribute::Weight(
                piet::FontWeight::new(font_weight),
            )),
            TextAttribute::TextColor(color) => {
                Ok(piet::TextAttribute::TextColor(piet::Color::from(color)))
            }
            TextAttribute::Style(style) => {
                Ok(piet::TextAttribute::Style(piet::FontStyle::from(style)))
            }
            TextAttribute::Underline(underline) => Ok(piet::TextAttribute::Underline(underline)),
            TextAttribute::Strikethrough(strikethrough) => {
                Ok(piet::TextAttribute::Strikethrough(strikethrough))
            }
        }

View on GitHub (pinned to bbc5354502)