ocrmypdf/OCRmyPDF · critical · FileNotFoundError

Required fallback font not found: {font_path}

Error message

Required fallback font not found: {font_path}

What it means

FontProvider loads its bundled font table; Occulta (the glyphless 'invisible text' font used for the OCR sandwich) is mandatory. If Occulta's .ttf file is missing from the font directory, _load_fonts() raises FileNotFoundError during FontProvider construction.

Source

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

        """Initialize builtin font provider.

        Args:
            font_dir: Directory containing font files. If None, uses
                      the default ocrmypdf/data directory.
        """
        if font_dir is None:
            font_dir = Path(__file__).parent.parent / "data"
        self.font_dir = font_dir
        self._fonts: dict[str, FontManager] = {}
        self._load_fonts()

    def _load_fonts(self) -> None:
        """Load available fonts, logging warnings for missing ones."""
        for font_name, font_file in self.FONT_FILES.items():
            font_path = self.font_dir / font_file
            if not font_path.exists():
                if font_name == 'Occulta':
                    raise FileNotFoundError(
                        f"Required fallback font not found: {font_path}"
                    )
                log.warning(
                    "Font %s not found at %s - OCR output quality for some "
                    "scripts may be affected",
                    font_name,
                    font_path,
                )
                continue

            try:
                self._fonts[font_name] = FontManager(font_path)
            except Exception as e:
                if font_name == 'Occulta':
                    raise ValueError(
                        f"Failed to load required fallback font {font_file}: {e}"
                    ) from e
                log.warning(

View on GitHub (pinned to 5074a0b0e1)

Solutions

1. Reinstall ocrmypdf cleanly (pip install --force-reinstall ocrmypdf) to restore bundled fonts.
2. If using a custom font_dir, copy the package's bundled font files (including Occulta) into it.

from importlib.resources import files
p = files('ocrmypdf') / 'font'  # verify packaged fonts exist
assert any('Occulta' in f.name for f in p.iterdir()), 'bundled Occulta.ttf missing'

try:
    provider = FontProvider(...)
except FileNotFoundError as e:
    if 'Required fallback font' in str(e):
        reinstall_ocrmypdf()

When it happens

Trigger: Instantiating FontProvider (directly or via a pipeline run) where font_dir lacks the Occulta font file — e.g. a broken package install or a custom font_dir passed without copying the bundled fonts.

Common situations: Partial wheel installs, pruning 'data files' from packages, or pointing font_dir at a directory that only has optional script fonts.

Related errors

• Failed to load required fallback font {font_file}: {e}
• At least one provider is required
• No fallback font available from any provider
• 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/571d33e33bb3c233. Report an issue: GitHub.