docling-project/docling · error · RuntimeError

Failed to load label mapping from model config at {model_fol

Error message

Failed to load label mapping from model config at {model_folder}: {exc}

What it means

Raised as RuntimeError by HfVisionModelMixin._load_label_mapping when loading the HF config fails or config.id2label is missing/malformed. Vision layout models map predicted class ids to label names via config.id2label; without it predictions cannot be interpreted.

Source

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

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

    def get_label_mapping(self) -> Dict[int, str]:
        """Get the label mapping for this model."""
        return self._id_to_label

    @staticmethod
    def _as_float(value: Any) -> float:
        if isinstance(value, Real):
            return float(value)

        if isinstance(value, np.ndarray):
            if value.size != 1:
                raise TypeError(
                    f"Expected scalar-like ndarray with size 1, got shape={value.shape}"
                )
            return float(value.reshape(-1)[0])

View on GitHub (pinned to 61d76f1ff3)

Solutions

Check the ': {exc}' suffix for the root cause (usually FileNotFoundError on config.json or AttributeError on id2label).
Ensure config.json is present in the model folder and re-download artifacts if incomplete.
For fine-tuned models, re-save the model with save_pretrained so id2label is serialized into config.json.

Example fix

# before: model folder missing config.json
# after: restore it from the base repo
# huggingface-cli download <repo_id> config.json --local-dir /models/layout

Defensive patterns

Strategy: try-catch

Validate before calling

from pathlib import Path
assert (Path(model_folder) / 'config.json').exists(), 'config.json missing'

Try / catch

try:
    model = MyVisionModel(...)
except RuntimeError as e:
    if 'label mapping' in str(e):
        raise RuntimeError('model artifacts incomplete: config.json/id2label missing') from e
    raise

Prevention

Ship complete model artifacts (config.json with id2label) when self-hosting fine-tunes.
Save fine-tuned models with save_pretrained so id2label is serialized.
Validate artifacts with a load smoke test during deployment, not at request time.

When it happens

Trigger: AutoConfig.from_pretrained(model_folder) raises (missing/corrupt config.json), or config.id2label does not exist / is not a mapping of int->str in the model's config.

Common situations: Model artifacts copied without config.json; a repo revision whose config lacks id2label; custom fine-tuned repos where the label mapping was not saved into the config.

Related errors

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