docling-project/docling · error · NotImplementedError

{repo_id} is supported by the Transformers engine only with

Error message

{repo_id} is supported by the Transformers engine only with transformers<5, but you have {transformers_version=}. Use a transformers-v4 environment, or use the vLLM engine.

What it means

Dots-family models (repo ids in _DOTS_REPO_IDS) are only supported by the Transformers engine on transformers major version 4. If the installed transformers is 5.x or newer, model resolution raises NotImplementedError and points you to either a transformers-v4 environment or the vLLM engine.

Source

Thrown at docling/models/inference_engines/vlm/transformers_engine.py:183

            repo_id: HuggingFace repository ID
            revision: Model revision
            model_type: Type of model architecture
        """
        transformers_version = importlib.metadata.version("transformers")
        parsed_transformers_version = version.parse(transformers_version)

        # Check for Phi-4 compatibility
        if (
            repo_id == "microsoft/Phi-4-multimodal-instruct"
            and parsed_transformers_version >= version.parse("4.52.0")
        ):
            raise NotImplementedError(
                f"Phi 4 only works with transformers<4.52.0 but you have {transformers_version=}. "
                f"Please downgrade by running: pip install -U 'transformers<4.52.0'"
            )
        is_dots_model = repo_id in _DOTS_REPO_IDS
        if is_dots_model and parsed_transformers_version.major >= 5:
            raise NotImplementedError(
                f"{repo_id} is supported by the Transformers engine only with "
                f"transformers<5, but you have {transformers_version=}. "
                "Use a transformers-v4 environment, or use the vLLM engine."
            )
        if repo_id in _DOTS_FLASH_ATTN_REQUIRED_REPO_IDS:
            _ensure_dots_flash_attn_import()

        # Download or locate model artifacts using shared utility
        def download_wrapper(repo_id: str, revision: str) -> Path:
            return self.download_models(repo_id, revision=revision)

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

View on GitHub (pinned to 61d76f1ff3)

Solutions

Create/use a dedicated transformers-v4 environment (pip install 'transformers>=4,<5') for Dots models
Or switch the pipeline to the vLLM engine (VllmVlmEngineOptions), which supports Dots on newer stacks
Pin transformers<5 in the project manifest to prevent accidental upgrades

Example fix

# before (transformers 5.x installed)
model_config = EngineModelConfig(repo_id='rednote-hilab/dots.mocr')
# TransformersVlmEngine(...) -> NotImplementedError

# after (option A: transformers-v4 env)
# terminal: pip install 'transformers>=4,<5'
# after (option B: vLLM engine)
options = VllmVlmEngineOptions()
engine = VllmVlmEngine(options=options, model_config=model_config, ...)

Defensive patterns

Strategy: validation

Validate before calling

import importlib.metadata
from packaging.version import Version

tv = Version(importlib.metadata.version('transformers'))
DOTS_MODELS = {'rednote-hilab/dots.mocr'}  # keep in sync with _DOTS_REPO_IDS
if repo_id in DOTS_MODELS and tv.major >= 5:
    raise SystemExit(f'{repo_id} needs a transformers-v4 environment or the vLLM engine (found transformers {tv})')

Try / catch

try:
    engine.initialize()
except NotImplementedError as e:
    if 'transformers-v4' in str(e):
        # rerun in a transformers-v4 env or rebuild with VllmVlmEngineOptions
        raise SystemExit('Use a transformers-v4 environment or the vLLM engine for Dots models') from e
    raise

Prevention

Pin 'transformers>=4,<5' in environments that serve Dots models
Keep separate environments for Dots (v4) and models requiring transformers 5
Add a packaging.version guard at pipeline startup before any model download happens

When it happens

Trigger: Loading a Dots model (e.g. rednote-hilab/dots.mocr or related repo ids) with TransformersVlmEngine while importlib.metadata reports transformers with major >= 5.

Common situations: A fresh install in a period where transformers 5 is on PyPI; upgrading transformers for another model and then returning to a Dots pipeline; sharing one environment between models with conflicting transformers requirements.

Related errors

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