docling-project/docling · error · NotImplementedError

{self.vlm_options.repo_id} is supported by the Transformers

Error message

{self.vlm_options.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

For the dots.ocr / dots.mocr models, the Transformers engine only works on transformers 4.x. If the major version is 5 or newer, Docling raises NotImplementedError and points you to either a transformers-v4 environment or the vLLM engine, which still supports these models.

Source

Thrown at docling/models/vlm_pipeline_models/hf_transformers_model.py:87

                AutoProcessor,
                BitsAndBytesConfig,
                GenerationConfig,
            )

            transformers_version = importlib.metadata.version("transformers")
            parsed_transformers_version = version.parse(transformers_version)
            if (
                self.vlm_options.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 "
                    f"{transformers_version=}. Please downgrade by running: "
                    "pip install -U 'transformers<4.52.0'"
                )
            is_dots_model = self.vlm_options.repo_id in _DOTS_REPO_IDS
            if is_dots_model and parsed_transformers_version.major >= 5:
                raise NotImplementedError(
                    f"{self.vlm_options.repo_id} is supported by the Transformers "
                    f"engine only with transformers<5, but you have "
                    f"{transformers_version=}. Use a transformers-v4 environment, "
                    "or use the vLLM engine."
                )
            if self.vlm_options.repo_id in _DOTS_FLASH_ATTN_REQUIRED_REPO_IDS:
                _ensure_dots_flash_attn_import()

            self.device = decide_device(
                accelerator_options.device,
                supported_devices=vlm_options.supported_devices,
            )
            _log.debug(f"Available device for VLM: {self.device}")

            self.use_cache = vlm_options.use_kv_cache
            self.max_new_tokens = vlm_options.max_new_tokens
            self.temperature = vlm_options.temperature

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Create/use a transformers-v4 environment (docling's transformers-v4 extra pins this) and run Docling there
2. Switch VlmOptions to the vLLM engine for these models, which does not depend on the 4.x line
3. Pin transformers<5 in your project requirements so upgrades cannot break it silently

Example fix

# before: transformers 5.x installed
vlm_options.repo_id = "rednote-hilab/dots.ocr"  # NotImplementedError
# after
# pip install 'transformers>=4,<5'
vlm_options.repo_id = "rednote-hilab/dots.ocr"

from packaging.version import Version
import transformers

DOTS = {'rednote-hilab/dots.ocr', 'rednote-hilab/dots.mocr'}
if vlm_options.repo_id in DOTS:
    assert Version(transformers.__version__).major < 5, 'dots models need transformers 4.x or the vLLM engine'

try:
    model = HuggingFaceTransformersVlmModel(...)
except NotImplementedError as e:
    if 'transformers<5' in str(e):
        vlm_options.engine = 'vllm'  # switch engine instead of downgrading shared env
        model = None  # rebuild via the vLLM engine
    else:
        raise

When it happens

Trigger: Setting vlm_options.repo_id to 'rednote-hilab/dots.ocr' or 'rednote-hilab/dots.mocr' with the Transformers engine while importlib.metadata.version('transformers') reports major version >= 5.

Common situations: Fresh installs that pull the newly released transformers 5.x; environments where another tool forced a transformers 5 upgrade; CI images rebuilt after transformers 5 shipped.

Related errors

• {repo_id} is supported by the Transformers engine only with
• rednote-hilab/dots.mocr requires flash-attn with the Transfo
• Phi 4 only works with transformers<4.52.0 but you have {tran
• Phi 4 only works with transformers<4.52.0 but you have {tran
• Unknown prompt style `{self.vlm_options.transformers_prompt_

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