ocrmypdf/OCRmyPDF · error · RuntimeError

No fallback font available from any provider

Error message

No fallback font available from any provider

What it means

get_fallback_font() iterates all registered providers calling get_fallback_font(); providers that don't implement it raise NotImplementedError/AttributeError/KeyError which are skipped. If every provider is exhausted, RuntimeError indicates no glyphless fallback (Occulta) could be supplied by any configured provider.

Source

Thrown at src/ocrmypdf/font/font_provider.py:248

        return None

    def get_fallback_font(self) -> FontManager:
        """Get the glyphless fallback font.

        Tries each provider until one provides a fallback font.

        Returns:
            FontManager for the fallback font

        Raises:
            RuntimeError: If no provider can provide a fallback font
        """
        for provider in self.providers:
            try:
                return provider.get_fallback_font()
            except (NotImplementedError, AttributeError, KeyError):
                continue
        raise RuntimeError("No fallback font available from any provider")

View on GitHub (pinned to 5074a0b0e1)

Solutions

1. Add BuiltinFontProvider to the providers list so Occulta.ttf is available.
2. If you only render non-sandwich output, avoid calling get_fallback_font() in that code path.

Example fix

# before
chain = FontProviderChain([SystemFontProvider(font_dir)])
font = chain.get_fallback_font()
# after
chain = FontProviderChain([SystemFontProvider(font_dir), BuiltinFontProvider(builtin_dir)])
font = chain.get_fallback_font()

has_fallback = any(
    hasattr(p, 'get_fallback_font') and not getattr(p, 'NO_FALLBACK', False)
    for p in chain.providers
)
assert has_fallback, 'add BuiltinFontProvider for Occulta fallback'

try:
    font = chain.get_fallback_font()
except RuntimeError:
    font = BuiltinFontProvider(builtin_dir).get_fallback_font()

When it happens

Trigger: Building a chain of only SystemFontProvider (or other providers without fallback support) and calling get_fallback_font() — common when assembling PDFs with visible/OCR text.

Common situations: Custom plugin setups that prefer system fonts and drop BuiltinFontProvider; sandboxed environments where the builtin font dir was excluded.

Related errors

• At least one provider is required
• Required fallback font not found: {font_path}
• Failed to load required fallback font {font_file}: {e}
• SystemFontProvider does not provide a fallback font. Use Bui
• --redo-ocr (or --mode redo) is not currently compatible with

AI-assisted analysis of ocrmypdf/OCRmyPDF@5074a0b0e1 (2026-08-27). Data as JSON: /api/errors/0fa6e7791e14b1a3. Report an issue: GitHub.