docling-project/docling · error · FileNotFoundError

artifacts_path ({artifacts_path}) does not contain the check

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.

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)

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.