docling-project/docling · error · ValueError

{type(self).__name__} requires model_config with repo_id

Error message

{type(self).__name__} requires model_config with repo_id

What it means

Raised by HfVisionModelMixin._init_hf_vision_model when the engine model config is None or has no repo_id. HF-backed vision inference engines resolve their weights from a Hugging Face repo id; without it the model cannot be downloaded or located locally.

Source

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

    from docling.datamodel.stage_model_specs import EngineModelConfig

_log = logging.getLogger(__name__)


class HfVisionModelMixin(HuggingFaceModelDownloadMixin):
    """Shared utility mixin for HF vision model loading and label conversion."""

    def _init_hf_vision_model(
        self,
        *,
        model_config: Optional[EngineModelConfig],
        accelerator_options: AcceleratorOptions,
        artifacts_path: Optional[Union[Path, str]],
        model_family_name: str,
    ) -> None:
        if model_config is None or model_config.repo_id is None:
            raise ValueError(
                f"{type(self).__name__} requires model_config with repo_id"
            )

        self._model_config: EngineModelConfig = model_config
        self._repo_id: str = model_config.repo_id
        self._accelerator_options = accelerator_options
        self._artifacts_path = (
            artifacts_path if artifacts_path is None else Path(artifacts_path)
        )
        self._model_family_name = model_family_name
        self._processor: Optional[BaseImageProcessor] = None
        self._id_to_label: Dict[int, str] = {}

    def _resolve_model_folder(self, repo_id: str, revision: str) -> Path:
        """Resolve model folder from artifacts_path or HF download."""

        def download_wrapper(download_repo_id: str, download_revision: str) -> Path:
            _log.info(

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Set repo_id on the model config to a valid Hugging Face model repository, e.g. 'ds4sd/docling-layout'.
2. If you intended to run fully remote inference, use the remote engine/config variant instead of the HF-backed one.
3. If you meant to use a local snapshot, still set repo_id (it keys the local cache) or supply the resolved artifacts_path alongside it.

Example fix

# before
model_config = EngineModelConfig(repo_id=None, artifacts_path='/models/layout')

# after
model_config = EngineModelConfig(repo_id='ds4sd/docling-layout', artifacts_path='/models/layout')

if model_config is None or not model_config.repo_id:
    raise ValueError('EngineModelConfig.repo_id is required for HF vision engines')

def has_repo_id(model_config) -> bool:
    return model_config is not None and bool(getattr(model_config, 'repo_id', None))

When it happens

Trigger: Constructing a KServe/HF vision inference model whose EngineModelConfig lacks repo_id (e.g. only artifacts_path or a remote URL was configured), or passing model_config=None.

Common situations: Switching a model family from a remote inference endpoint to local HF weights and forgetting to set repo_id in the model config; YAML/pydantic config where repo_id field is omitted; copy-pasting a remote-engine config for an HF-backed engine.

Related errors

• Failed to load label mapping from model config at {model_fol
• Image processor config not found: {preprocessor_config}
• Failed to load image processor from {model_folder}: {exc}
• Failed to load model from {model_folder}: {exc}
• Unknown EBCDIC codec {encoding!r}.

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