{"record":{"id":"d6172348d0279227","repo":"docling-project/docling","slug":"artifacts-path-artifacts-path-does-not-contain","errorCode":null,"errorMessage":"artifacts_path ({artifacts_path}) does not contain the checkpoint {repo_id}/{filename} required by ASR model '{self.model_name}'. Prefetch it with: hf download {repo_id} {filename} --cache-dir \"{artifacts_path}\"","messagePattern":"artifacts_path \\((.+?)\\) does not contain the checkpoint (.+?)/(.+?) required by ASR model '(.+?)'\\. Prefetch it with: hf download (.+?) (.+?) --cache-dir \"(.+?)\"","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"docling/pipeline/asr_transcriber.py","lineNumber":252,"sourceCode":"                from huggingface_hub.utils import LocalEntryNotFoundError\n\n                repo_id, filename = distil_checkpoint\n                _log.info(\n                    f\"loading {self.model_name} from OpenAI-format checkpoint \"\n                    f\"{repo_id}/{filename}\"\n                )\n                if artifacts_path is not None:\n                    # artifacts_path means fully-offline operation: resolve the\n                    # checkpoint from the local cache and never download.\n                    try:\n                        checkpoint_path = hf_hub_download(\n                            repo_id=repo_id,\n                            filename=filename,\n                            cache_dir=str(artifacts_path),\n                            local_files_only=True,\n                        )\n                    except LocalEntryNotFoundError as err:\n                        raise FileNotFoundError(\n                            f\"artifacts_path ({artifacts_path}) does not contain \"\n                            f\"the checkpoint {repo_id}/{filename} required by ASR \"\n                            f\"model '{self.model_name}'. Prefetch it with: \"\n                            f\"hf download {repo_id} {filename} \"\n                            f'--cache-dir \"{artifacts_path}\"'\n                        ) from err\n                else:\n                    checkpoint_path = hf_hub_download(\n                        repo_id=repo_id, filename=filename\n                    )\n                self.model = whisper.load_model(\n                    name=checkpoint_path, device=self.device\n                )\n            elif artifacts_path is not None:\n                _log.info(f\"loading {self.model_name} from {artifacts_path}\")\n                self.model = whisper.load_model(\n                    name=self.model_name,\n                    device=self.device,","sourceCodeStart":234,"sourceCodeEnd":270,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/pipeline/asr_transcriber.py#L234-L270","documentation":"In fully-offline mode (artifacts_path set), the whisper transcriber resolves its checkpoint with hf_hub_download(..., local_files_only=True); if the cache under artifacts_path lacks repo_id/filename, huggingface_hub raises LocalEntryNotFoundError and docling wraps it in FileNotFoundError with the exact prefetch command. This guarantees offline runs never silently hit the network.","triggerScenarios":"AsrOptions(artifacts_path=...) (or the global artifacts_path setting) where the whisper model repo (e.g. openai/whisper-tiny with its .pt filename) was never downloaded into that cache dir. Only thrown when artifacts_path is not None; without it, the model downloads on demand.","commonSituations":"Offline/air-gapped ASR deployments; sharing an artifacts_path between PDF pipelines (layout models present) and ASR (whisper repo missing); cache populated for a different whisper size (tiny vs base) than asr_options.model_name requests.","solutions":["Run the exact command from the message: hf download <repo_id> <filename> --cache-dir \"<artifacts_path>\"","Or pre-populate the cache by running once without artifacts_path so hf_hub_download fetches it, then point artifacts_path at that cache","Verify the cache layout: <artifacts_path>/models--<org>--<model>/snapshots/<sha>/<filename> must exist for the configured whisper model name"],"exampleFix":"# before\nAsrOptions(artifacts_path=Path('/opt/models'))  # whisper repo absent\n\n# after\n# shell: hf download openai/whisper-tiny model.pt --cache-dir /opt/models\nAsrOptions(artifacts_path=Path('/opt/models'))","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef whisper_checkpoint_cached(artifacts_path: Path, repo_id: str, filename: str) -> bool:\n    org, name = repo_id.split('/')\n    repo_dir = artifacts_path / f'models--{org}--{name}'\n    return repo_dir.is_dir() and any(p.name == filename for p in repo_dir.rglob(filename)) or any(\n        snap.name == filename for snap in (repo_dir / 'snapshots').rglob(filename)\n    )","typeGuard":null,"tryCatchPattern":"try:\n    asr = InlineAsrPipeline(opts)\nexcept FileNotFoundError as e:\n    if 'Prefetch it with' in str(e):\n        run_prefetch = input('Whisper checkpoint missing. Run the hf download command now? [y/N]')\n        ...  # shell out to `hf download ...` then retry once\n    raise","preventionTips":["Bake `hf download <whisper-repo> --cache-dir <artifacts>` into offline image builds","In fully-offline mode, verify the HF cache layout (models--org--name/snapshots) for every model before startup"],"tags":["asr","whisper","offline","huggingface","artifacts-path"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}