What causes "The following RapidOCR paths do not exist: {listed}" in docling-project/docling?

Correct each listed path so it points at an existing file (the error lists every offender).

docling-project/docling · error · FileNotFoundError

The following RapidOCR paths do not exist: {listed}

Error message

The following RapidOCR paths do not exist:
{listed}

What it means

RapidOcrOptions lets you pin individual model artifact paths (det/cls/rec model files, rec keys, font). Before initializing the engine, Docling checks every non-None pinned path exists on disk; any missing file is collected into a FileNotFoundError listing all of them at once.

Source

Thrown at docling/models/stages/ocr/rapid_ocr_model.py:334

            rec_model_path = self.options.rec_model_path
            rec_keys_path = self.options.rec_keys_path
            font_path = self.options.font_path

            # A pinned path that does not exist is a configuration error
            missing_pinned = [
                model_path
                for model_path in (
                    det_model_path,
                    cls_model_path,
                    rec_model_path,
                    rec_keys_path,
                    font_path,
                )
                if model_path is not None and not Path(model_path).exists()
            ]
            if missing_pinned:
                listed = "\n".join(f"  - {path}" for path in missing_pinned)
                raise FileNotFoundError(
                    f"The following RapidOCR paths do not exist:\n{listed}"
                )

            # Params forwarded to RapidOCR only in the library-managed flow (no artifacts_path)
            lang_params: dict[str, object] = {}

            if artifacts_path is not None:
                # artifacts_path means fully-offline operation
                target_dir = artifacts_path / self._model_repo_folder
                artifacts: dict[str, _RapidOcrArtifact] = _rapidocr_artifacts(
                    target_dir,
                    backend_enum,
                    ppocr_version,
                    rec_lang,
                    need_det=det_model_path is None,
                    need_cls=cls_model_path is None,
                    need_rec=rec_model_path is None,
                )

View on GitHub (pinned to 61d76f1ff3)

Solutions

Correct each listed path so it points at an existing file (the error lists every offender).
Prefer absolute pathlib.Path values for pinned artifacts to avoid cwd-dependent resolution.
If you want RapidOCR to manage downloads itself, unset the pinned path(s) (leave them None).

Example fix

# before
RapidOcrOptions(det_model_path="models/det.onnx")  # cwd-dependent, missing

# after
from pathlib import Path
RapidOcrOptions(det_model_path=str(Path("/opt/models").resolve() / "det.onnx"))

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

pinned = {
    "det_model_path": det, "cls_model_path": cls, "rec_model_path": rec,
    "rec_keys_path": keys, "font_path": font,
}
missing = [k for k, v in pinned.items() if v is not None and not Path(v).is_file()]
if missing:
    raise ConfigError(f"RapidOCR pinned paths missing: {missing}")

Try / catch

try:
    RapidOcrModel(options=RapidOcrOptions(det_model_path=..., ...))
except FileNotFoundError as e:
    log.error("pinned RapidOCR artifacts unavailable: %s", e)
    raise  # do not silently fall back to different models

Prevention

Store pinned model paths in one config section and validate all of them at startup.
Use absolute paths from a single ARTIFACTS_DIR constant.
Checksum or existence-check artifacts as part of deployment verification.

When it happens

Trigger: Setting det_model_path / cls_model_path / rec_model_path / rec_keys_path / font_path on RapidOcrOptions to paths that do not exist — wrong absolute path, moved artifacts directory, or a relative path interpreted from a different working directory.

Common situations: Hardcoded paths from another machine; artifacts downloaded into a different location than the config points to; relative paths breaking when the process cwd changes (container, service, notebook).

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/200ef02f0d01bb04. Report an issue: GitHub.