docling-project/docling · error · FileNotFoundError

RapidOCR artifacts not found or incomplete in artifacts_path

Error message

RapidOCR artifacts not found or incomplete in artifacts_path.
Expected under: {target_dir}
Resolved: backend={self.options.backend} ppocr_version={ppocr_version.value} rec_lang={rec_lang}
Missing files:
{listed}
Prefetch them with:
  docling-tools models download rapidocr --rapidocr-backend-lang {self.options.backend}:{lang} -o {artifacts_path}
Or unset artifacts_path to let RapidOCR resolve and download the checkpoints itself.

What it means

With artifacts_path set (fully-offline mode), Docling resolves which RapidOCR files should exist for the chosen backend/language/PP-OCR version and verifies each one is present under artifacts_path/<model_repo_folder>. Missing files produce a FileNotFoundError that includes the resolved backend, ppocr_version, rec_lang, the missing file list, and the exact 'docling-tools models download' command to prefetch them.

Source

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

                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,
                )
                missing = [
                    dest
                    for artifact in artifacts.values()
                    for dest in artifact.files
                    if not dest.is_file()
                ]
                if missing:
                    listed = "\n".join(f"  - {path}" for path in missing)
                    # `lang` is the user's own token, so the hint mirrors their config.
                    raise FileNotFoundError(
                        "RapidOCR artifacts not found or incomplete in artifacts_path.\n"
                        f"Expected under: {target_dir}\n"
                        f"Resolved: backend={self.options.backend} "
                        f"ppocr_version={ppocr_version.value} rec_lang={rec_lang}\n"
                        f"Missing files:\n{listed}\n"
                        "Prefetch them with:\n"
                        f"  docling-tools models download rapidocr "
                        f"--rapidocr-backend-lang {self.options.backend}:{lang} "
                        f"-o {artifacts_path}\n"
                        "Or unset artifacts_path to let RapidOCR resolve and download "
                        "the checkpoints itself."
                    )

                if "det" in artifacts:
                    det_model_path = str(artifacts["det"].model_path)
                if "cls" in artifacts:
                    cls_model_path = str(artifacts["cls"].model_path)
                if "rec" in artifacts:

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Run the prefetch command shown in the error message: docling-tools models download rapidocr --rapidocr-backend-lang <backend>:<lang> -o <artifacts_path>, using the backend and lang from the error text.
2. Make sure the lang and backend in that command match the ones in your RapidOcrOptions exactly, so the right model files land in the right folder.
3. If online operation is acceptable, unset artifacts_path and let RapidOCR resolve/download checkpoints itself.

Example fix

# before: offline dir missing artifacts for torch:chinese
# FileNotFoundError at init

# after
$ docling-tools models download rapidocr --rapidocr-backend-lang torch:chinese -o /path/to/artifacts

from pathlib import Path
# Mirror the resolution and check the expected folder is populated before init:
target = Path(artifacts_path) / "rapidocr"  # model repo cache folder
traineddata_like = list(target.rglob("*.onnx")) + list(target.rglob("*.txt"))
if artifacts_path is not None and not traineddata_like:
    raise SystemExit(
        f"artifacts missing under {target}; run: "
        "docling-tools models download rapidocr "
        f"--rapidocr-backend-lang {backend}:{lang} -o {artifacts_path}"
    )

try:
    pipeline.initialize()
except FileNotFoundError as e:
    msg = str(e)
    if "RapidOCR artifacts not found" in msg:
        # surface the embedded docling-tools prefetch command to the operator
        log.error("offline artifacts incomplete:\n%s", msg)
        raise
    raise

When it happens

Trigger: Running offline (artifacts_path set on the model or pipeline) with an artifacts directory that is empty or was populated for a different backend/language combination — e.g. artifacts downloaded for onnxruntime+english but options now say torch+chinese, so the resolved target files were never fetched.

Common situations: Air-gapped deployments where models must be pre-provisioned; reusing one artifacts cache across configurations with different langs/backends; partial or interrupted 'docling-tools models download' runs.

Related errors

• The following RapidOCR paths do not exist: {listed}
• ONNX model file '{model_filename}' not found: {model_path}
• Model '{repo_id}' not found in artifacts_path. Expected loca
• Model '{repo_id}' not found in artifacts_path. Expected loca
• Nemotron OCR artifacts not found or incomplete in artifacts_

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