docling-project/docling · error · FileNotFoundError

artifacts_path ( ) does not contain the checkpoint /…

Error message

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}"

What it means

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.

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

Example fix

# before
AsrOptions(artifacts_path=Path('/opt/models'))  # whisper repo absent

# after
# shell: hf download openai/whisper-tiny model.pt --cache-dir /opt/models
AsrOptions(artifacts_path=Path('/opt/models'))

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def whisper_checkpoint_cached(artifacts_path: Path, repo_id: str, filename: str) -> bool:
    org, name = repo_id.split('/')
    repo_dir = artifacts_path / f'models--{org}--{name}'
    return repo_dir.is_dir() and any(p.name == filename for p in repo_dir.rglob(filename)) or any(
        snap.name == filename for snap in (repo_dir / 'snapshots').rglob(filename)
    )

Try / catch

try:
    asr = InlineAsrPipeline(opts)
except FileNotFoundError as e:
    if 'Prefetch it with' in str(e):
        run_prefetch = input('Whisper checkpoint missing. Run the hf download command now? [y/N]')
        ...  # shell out to `hf download ...` then retry once
    raise

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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

Appendix: source

Thrown at docling/pipeline/asr_transcriber.py:252

                from huggingface_hub.utils import LocalEntryNotFoundError

                repo_id, filename = distil_checkpoint
                _log.info(
                    f"loading {self.model_name} from OpenAI-format checkpoint "
                    f"{repo_id}/{filename}"
                )
                if artifacts_path is not None:
                    # artifacts_path means fully-offline operation: resolve the
                    # checkpoint from the local cache and never download.
                    try:
                        checkpoint_path = hf_hub_download(
                            repo_id=repo_id,
                            filename=filename,
                            cache_dir=str(artifacts_path),
                            local_files_only=True,
                        )
                    except LocalEntryNotFoundError as err:
                        raise FileNotFoundError(
                            f"artifacts_path ({artifacts_path}) does not contain "
                            f"the checkpoint {repo_id}/{filename} required by ASR "
                            f"model '{self.model_name}'. Prefetch it with: "
                            f"hf download {repo_id} {filename} "
                            f'--cache-dir "{artifacts_path}"'
                        ) from err
                else:
                    checkpoint_path = hf_hub_download(
                        repo_id=repo_id, filename=filename
                    )
                self.model = whisper.load_model(
                    name=checkpoint_path, device=self.device
                )
            elif artifacts_path is not None:
                _log.info(f"loading {self.model_name} from {artifacts_path}")
                self.model = whisper.load_model(
                    name=self.model_name,
                    device=self.device,

View on GitHub (pinned to 61d76f1ff3)