{"record":{"id":"b0019eb445eab51e","repo":"docling-project/docling","slug":"rapidocr-artifacts-not-found-or-incomplete-in-arti","errorCode":null,"errorMessage":"RapidOCR artifacts not found or incomplete in artifacts_path.\nExpected under: {target_dir}\nResolved: backend={self.options.backend} ppocr_version={ppocr_version.value} rec_lang={rec_lang}\nMissing files:\n{listed}\nPrefetch them with:\n  docling-tools models download rapidocr --rapidocr-backend-lang {self.options.backend}:{lang} -o {artifacts_path}\nOr unset artifacts_path to let RapidOCR resolve and download the checkpoints itself.","messagePattern":"RapidOCR artifacts not found or incomplete in artifacts_path\\.\nExpected under: (.+?)\nResolved: backend=(.+?) ppocr_version=(.+?) rec_lang=(.+?)\nMissing files:\n(.+?)\nPrefetch them with:\n  docling-tools models download rapidocr --rapidocr-backend-lang (.+?):(.+?) -o (.+?)\nOr unset artifacts_path to let RapidOCR resolve and download the checkpoints itself\\.","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"docling/models/stages/ocr/rapid_ocr_model.py","lineNumber":362,"sourceCode":"                artifacts: dict[str, _RapidOcrArtifact] = _rapidocr_artifacts(\n                    target_dir,\n                    backend_enum,\n                    ppocr_version,\n                    rec_lang,\n                    need_det=det_model_path is None,\n                    need_cls=cls_model_path is None,\n                    need_rec=rec_model_path is None,\n                )\n                missing = [\n                    dest\n                    for artifact in artifacts.values()\n                    for dest in artifact.files\n                    if not dest.is_file()\n                ]\n                if missing:\n                    listed = \"\\n\".join(f\"  - {path}\" for path in missing)\n                    # `lang` is the user's own token, so the hint mirrors their config.\n                    raise FileNotFoundError(\n                        \"RapidOCR artifacts not found or incomplete in artifacts_path.\\n\"\n                        f\"Expected under: {target_dir}\\n\"\n                        f\"Resolved: backend={self.options.backend} \"\n                        f\"ppocr_version={ppocr_version.value} rec_lang={rec_lang}\\n\"\n                        f\"Missing files:\\n{listed}\\n\"\n                        \"Prefetch them with:\\n\"\n                        f\"  docling-tools models download rapidocr \"\n                        f\"--rapidocr-backend-lang {self.options.backend}:{lang} \"\n                        f\"-o {artifacts_path}\\n\"\n                        \"Or unset artifacts_path to let RapidOCR resolve and download \"\n                        \"the checkpoints itself.\"\n                    )\n\n                if \"det\" in artifacts:\n                    det_model_path = str(artifacts[\"det\"].model_path)\n                if \"cls\" in artifacts:\n                    cls_model_path = str(artifacts[\"cls\"].model_path)\n                if \"rec\" in artifacts:","sourceCodeStart":344,"sourceCodeEnd":380,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/stages/ocr/rapid_ocr_model.py#L344-L380","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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.","If online operation is acceptable, unset artifacts_path and let RapidOCR resolve/download checkpoints itself."],"exampleFix":"# before: offline dir missing artifacts for torch:chinese\n# FileNotFoundError at init\n\n# after\n$ docling-tools models download rapidocr --rapidocr-backend-lang torch:chinese -o /path/to/artifacts","handlingStrategy":"validation","validationCode":"from pathlib import Path\n# Mirror the resolution and check the expected folder is populated before init:\ntarget = Path(artifacts_path) / \"rapidocr\"  # model repo cache folder\ntraineddata_like = list(target.rglob(\"*.onnx\")) + list(target.rglob(\"*.txt\"))\nif artifacts_path is not None and not traineddata_like:\n    raise SystemExit(\n        f\"artifacts missing under {target}; run: \"\n        \"docling-tools models download rapidocr \"\n        f\"--rapidocr-backend-lang {backend}:{lang} -o {artifacts_path}\"\n    )","typeGuard":null,"tryCatchPattern":"try:\n    pipeline.initialize()\nexcept FileNotFoundError as e:\n    msg = str(e)\n    if \"RapidOCR artifacts not found\" in msg:\n        # surface the embedded docling-tools prefetch command to the operator\n        log.error(\"offline artifacts incomplete:\\n%s\", msg)\n        raise\n    raise","preventionTips":["Make 'docling-tools models download' part of your image build for air-gapped setups.","Key your artifacts cache by (backend, lang) so different configs never share a folder.","Verify artifacts exist for the exact backend/lang pair after every config change."],"tags":["ocr","rapidocr","offline","artifacts","file-path"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}