docling-project/docling · error · FileNotFoundError

Image processor config not found: {preprocessor_config}

Error message

Image processor config not found: {preprocessor_config}

What it means

Raised as FileNotFoundError by HfVisionModelMixin._load_preprocessor when the resolved model folder does not contain preprocessor_config.json. The HF image processor cannot be constructed without that file, so this is a hard precondition before any image preprocessing.

Source

Thrown at docling/models/inference_engines/common/hf_vision_base.py:79

                repo_id=download_repo_id,
                revision=download_revision,
                local_dir=None,
                force=False,
                progress=False,
            )

        return resolve_model_artifacts_path(
            repo_id=repo_id,
            revision=revision,
            artifacts_path=self._artifacts_path,
            download_fn=download_wrapper,
        )

    def _load_preprocessor(self, model_folder: Path) -> BaseImageProcessor:
        """Load HuggingFace image processor from model folder."""
        preprocessor_config = model_folder / "preprocessor_config.json"
        if not preprocessor_config.exists():
            raise FileNotFoundError(
                f"Image processor config not found: {preprocessor_config}"
            )

        try:
            from transformers import AutoImageProcessor

            _log.debug("Loading image processor from %s", model_folder)
            return AutoImageProcessor.from_pretrained(str(model_folder))
        except Exception as exc:
            raise RuntimeError(
                f"Failed to load image processor from {model_folder}: {exc}"
            )

    def _load_label_mapping(self, model_folder: Path) -> Dict[int, str]:
        """Load label mapping from HuggingFace model config."""
        try:
            from transformers import AutoConfig

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Verify the printed path actually contains the model files; if it is a wrong directory, fix artifacts_path or repo_id/revision.
2. Re-download the model (delete the partial snapshot / clear the HF cache for that repo) so preprocessor_config.json is fetched.
3. If you curate the folder manually, copy preprocessor_config.json (and config.json) from the HF repo alongside the weights.

Example fix

# before
accelerator_opts = ...
model = MyLayoutModel(...)  # artifacts_path='/models/layout' missing config

# after
# ensure the folder has the file:
# ls /models/layout/preprocessor_config.json
# if missing: huggingface-cli download <repo_id> --local-dir /models/layout

from pathlib import Path
folder = Path(artifacts_path) if artifacts_path else hf_snapshot_dir(repo_id, revision)
if not (folder / 'preprocessor_config.json').exists():
    raise FileNotFoundError(f'{folder} lacks preprocessor_config.json; re-download {repo_id}')

try:
    model = MyVisionModel(...)
except FileNotFoundError as e:
    if 'preprocessor_config' in str(e):
        redownload(repo_id)  # then retry once
        model = MyVisionModel(...)
    else:
        raise

When it happens

Trigger: The resolved artifacts folder (HF cache snapshot, local artifacts_path, or downloaded revision) lacks preprocessor_config.json — e.g. an incomplete download/copy, or pointing artifacts_path at a folder that only holds weights.

Common situations: Manual copy of a model repo that skipped config files; interrupted HF download leaving a partial snapshot; artifacts_path pointing at the wrong directory level; a repo revision that genuinely does not ship a preprocessor config.

Related errors

• {type(self).__name__} requires model_config with repo_id
• Failed to load image processor from {model_folder}: {exc}
• Failed to load label mapping from model config at {model_fol
• ONNX model file '{model_filename}' not found: {model_path}
• Failed to load model from {model_folder}: {exc}

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