matplotlib/matplotlib · error · ValueError

Failed to find any font, and fallback to the default font wa

Error message

Failed to find any font, and fallback to the default font was disabled

What it means

When font lookup finds no acceptable match, FontManager retries with the default family (DejaVu Sans) unless fallback_to_default=False, in which case _find_fonts_by_props raises ValueError. The error therefore means: the requested family (or font file) is not present in the current font cache/installed set and fallback was explicitly disabled.

Source

Thrown at lib/matplotlib/font_manager.py:1572

                else:
                    _log.warning("findfont: Font family %r not found.", family)

        # only add default family if no other font was found and
        # fallback_to_default is enabled
        if not fpaths:
            if fallback_to_default:
                dfamily = self.defaultFamily[fontext]
                cprop = prop.copy()
                cprop.set_family(dfamily)
                fpaths.append(
                    self.findfont(
                        cprop, fontext, directory,
                        fallback_to_default=True,
                        rebuild_if_missing=rebuild_if_missing,
                    )
                )
            else:
                raise ValueError("Failed to find any font, and fallback "
                                 "to the default font was disabled")

        return fpaths

    @lru_cache(1024)
    def _findfont_cached(self, prop, fontext, directory, fallback_to_default,
                         rebuild_if_missing, rc_params):

        prop = FontProperties._from_any(prop)

        fname = prop.get_file()
        if fname is not None:
            return fname

        if fontext == 'afm':
            fontlist = self.afmlist
        else:
            fontlist = self.ttflist

View on GitHub (pinned to b379c1b69e)

Solutions

1. Install or register the font: font_manager.fontManager.addfont('/path/to/font.ttf') (rebuild cache if installed system-wide)
2. Delete the stale cache so it rescans: rm -rf ~/.cache/matplotlib
3. Verify the exact family name with font_manager.get_font_names() or sorted({f.name for f in fontManager.ttflist})
4. Leave fallback_to_default at its default True if a substitute is acceptable

Example fix

# before
font_manager.findfont(FontProperties(family='Roboto'), fallback_to_default=False)

# after
from matplotlib import font_manager as fm
fm.fontManager.addfont('/usr/share/fonts/truetype/roboto/Roboto-Regular.ttf')
fm.findfont(FontProperties(family='Roboto'), fallback_to_default=False)

from matplotlib import font_manager as fm
available = {f.name for f in fm.fontManager.ttflist}
if family not in available:
    raise ValueError(f'{family!r} not installed; available: {sorted(available)[:10]} ...')

def font_is_registered(family):
    from matplotlib import font_manager as fm
    return any(f.name == family for f in fm.fontManager.ttflist)

try:
    path = fm.findfont(prop, fallback_to_default=False)
except ValueError:
    path = fm.findfont(prop)  # accept DejaVu Sans substitute

When it happens

Trigger: findfont(FontProperties(family='Arial'), fallback_to_default=False); mathtext or usetex output requesting a font absent from the cache; a newly installed OS font used before rebuilding the font cache.

Common situations: Minimal Docker/conda images without common fonts; fonts installed but the fontlist cache is stale; misspelled family names; MPLCONFIGDIR pointing at an empty directory.

Related errors

• Timed out running {cbook._pformat_subprocess(args)}
• Unterminated string starting at {start}
• Unterminated hex string starting at {start}
• Malformed hex string starting at {start}
• unmatched closing token {token}

AI-assisted analysis of matplotlib/matplotlib@b379c1b69e (2026-08-21). Data as JSON: /api/errors/2397abdcca6fa0a8. Report an issue: GitHub.