{"record":{"id":"1b4ad88636dbcb81","repo":"docling-project/docling","slug":"repo-id-is-supported-by-the-transformers-engine","errorCode":null,"errorMessage":"{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.","messagePattern":"(.+?) is supported by the Transformers engine only with transformers<5, but you have (.+?)\\. Use a transformers-v4 environment, or use the vLLM engine\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/vlm/transformers_engine.py","lineNumber":183,"sourceCode":"            repo_id: HuggingFace repository ID\n            revision: Model revision\n            model_type: Type of model architecture\n        \"\"\"\n        transformers_version = importlib.metadata.version(\"transformers\")\n        parsed_transformers_version = version.parse(transformers_version)\n\n        # Check for Phi-4 compatibility\n        if (\n            repo_id == \"microsoft/Phi-4-multimodal-instruct\"\n            and parsed_transformers_version >= version.parse(\"4.52.0\")\n        ):\n            raise NotImplementedError(\n                f\"Phi 4 only works with transformers<4.52.0 but you have {transformers_version=}. \"\n                f\"Please downgrade by running: pip install -U 'transformers<4.52.0'\"\n            )\n        is_dots_model = repo_id in _DOTS_REPO_IDS\n        if is_dots_model and parsed_transformers_version.major >= 5:\n            raise NotImplementedError(\n                f\"{repo_id} is supported by the Transformers engine only with \"\n                f\"transformers<5, but you have {transformers_version=}. \"\n                \"Use a transformers-v4 environment, or use the vLLM engine.\"\n            )\n        if repo_id in _DOTS_FLASH_ATTN_REQUIRED_REPO_IDS:\n            _ensure_dots_flash_attn_import()\n\n        # Download or locate model artifacts using shared utility\n        def download_wrapper(repo_id: str, revision: str) -> Path:\n            return self.download_models(repo_id, revision=revision)\n\n        artifacts_path = resolve_model_artifacts_path(\n            repo_id=repo_id,\n            revision=revision,\n            artifacts_path=self.artifacts_path,\n            download_fn=download_wrapper,\n        )\n","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/vlm/transformers_engine.py#L165-L201","documentation":"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.","triggerScenarios":"Loading a Dots model (e.g. rednote-hilab/dots.mocr or related repo ids) with TransformersVlmEngine while importlib.metadata reports transformers with major >= 5.","commonSituations":"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.","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"],"exampleFix":"# before (transformers 5.x installed)\nmodel_config = EngineModelConfig(repo_id='rednote-hilab/dots.mocr')\n# TransformersVlmEngine(...) -> NotImplementedError\n\n# after (option A: transformers-v4 env)\n# terminal: pip install 'transformers>=4,<5'\n# after (option B: vLLM engine)\noptions = VllmVlmEngineOptions()\nengine = VllmVlmEngine(options=options, model_config=model_config, ...)","handlingStrategy":"validation","validationCode":"import importlib.metadata\nfrom packaging.version import Version\n\ntv = Version(importlib.metadata.version('transformers'))\nDOTS_MODELS = {'rednote-hilab/dots.mocr'}  # keep in sync with _DOTS_REPO_IDS\nif repo_id in DOTS_MODELS and tv.major >= 5:\n    raise SystemExit(f'{repo_id} needs a transformers-v4 environment or the vLLM engine (found transformers {tv})')","typeGuard":null,"tryCatchPattern":"try:\n    engine.initialize()\nexcept NotImplementedError as e:\n    if 'transformers-v4' in str(e):\n        # rerun in a transformers-v4 env or rebuild with VllmVlmEngineOptions\n        raise SystemExit('Use a transformers-v4 environment or the vLLM engine for Dots models') from e\n    raise","preventionTips":["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"],"tags":["vlm","transformers","version-conflict","dots-ocr","vllm","dependency"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}