docling-project/docling · error · RuntimeError

Failed to load image processor from {model_folder}: {exc}

Error message

Failed to load image processor from {model_folder}: {exc}

What it means

Raised as RuntimeError by HfVisionModelMixin._load_preprocessor wrapping any exception from AutoImageProcessor.from_pretrained on the model folder. The original error is embedded in the message; common causes are transformers version incompatibilities, corrupt config files, or missing processor dependencies.

Source

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

            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

            config = AutoConfig.from_pretrained(str(model_folder))
            return {
                int(label_id): label_name
                for label_id, label_name in config.id2label.items()
            }
        except Exception as exc:
            raise RuntimeError(
                f"Failed to load label mapping from model config at {model_folder}: {exc}"
            )

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Read the ': {exc}' tail of the message — it carries the underlying transformers error; fix that root cause.
2. Upgrade or pin transformers to the version documented for the model family used by this Docling release.
3. If the config file is corrupt, re-download the model artifacts from the HF repo.

Example fix

# before: RuntimeError: Failed to load image processor ...: KeyError 'ImageProcessor'
# pin a compatible transformers
# uv add 'transformers==4.48.3'  # version required by this docling release

import json
from pathlib import Path
cfg = Path(model_folder) / 'preprocessor_config.json'
json.loads(cfg.read_text())  # fail early on malformed config

try:
    model = MyVisionModel(...)
except RuntimeError as e:
    if 'Failed to load image processor' in str(e):
        log.error('processor load failed: %s', e.__cause__ or e)
        raise  # fix transformers version / artifacts, do not retry

When it happens

Trigger: preprocessor_config.json exists but AutoImageProcessor.from_pretrained(model_folder) raises — unsupported processor_type in the installed transformers version, malformed JSON, or a processor class requiring an extra dependency.

Common situations: Downgraded/upgraded transformers so the processor class for the repo no longer exists; hand-edited or truncated preprocessor_config.json; model repo requiring newer feature-extractor APIs.

Related errors

• Failed to load model from {model_folder}: {exc}
• {type(self).__name__} requires model_config with repo_id
• Image processor config not found: {preprocessor_config}
• Failed to load label mapping from model config at {model_fol
• Failed to load model from {model_folder}: {e}

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