{"record":{"id":"bfe8a9a450cf85b4","repo":"docling-project/docling","slug":"self-vlm-options-repo-id-is-supported-by-the-tra","errorCode":null,"errorMessage":"{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.","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/vlm_pipeline_models/hf_transformers_model.py","lineNumber":87,"sourceCode":"                AutoProcessor,\n                BitsAndBytesConfig,\n                GenerationConfig,\n            )\n\n            transformers_version = importlib.metadata.version(\"transformers\")\n            parsed_transformers_version = version.parse(transformers_version)\n            if (\n                self.vlm_options.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 \"\n                    f\"{transformers_version=}. Please downgrade by running: \"\n                    \"pip install -U 'transformers<4.52.0'\"\n                )\n            is_dots_model = self.vlm_options.repo_id in _DOTS_REPO_IDS\n            if is_dots_model and parsed_transformers_version.major >= 5:\n                raise NotImplementedError(\n                    f\"{self.vlm_options.repo_id} is supported by the Transformers \"\n                    f\"engine only with transformers<5, but you have \"\n                    f\"{transformers_version=}. Use a transformers-v4 environment, \"\n                    \"or use the vLLM engine.\"\n                )\n            if self.vlm_options.repo_id in _DOTS_FLASH_ATTN_REQUIRED_REPO_IDS:\n                _ensure_dots_flash_attn_import()\n\n            self.device = decide_device(\n                accelerator_options.device,\n                supported_devices=vlm_options.supported_devices,\n            )\n            _log.debug(f\"Available device for VLM: {self.device}\")\n\n            self.use_cache = vlm_options.use_kv_cache\n            self.max_new_tokens = vlm_options.max_new_tokens\n            self.temperature = vlm_options.temperature\n","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/vlm_pipeline_models/hf_transformers_model.py#L69-L105","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Create/use a transformers-v4 environment (docling's transformers-v4 extra pins this) and run Docling there","Switch VlmOptions to the vLLM engine for these models, which does not depend on the 4.x line","Pin transformers<5 in your project requirements so upgrades cannot break it silently"],"exampleFix":"# before: transformers 5.x installed\nvlm_options.repo_id = \"rednote-hilab/dots.ocr\"  # NotImplementedError\n# after\n# pip install 'transformers>=4,<5'\nvlm_options.repo_id = \"rednote-hilab/dots.ocr\"","handlingStrategy":"validation","validationCode":"from packaging.version import Version\nimport transformers\n\nDOTS = {'rednote-hilab/dots.ocr', 'rednote-hilab/dots.mocr'}\nif vlm_options.repo_id in DOTS:\n    assert Version(transformers.__version__).major < 5, 'dots models need transformers 4.x or the vLLM engine'","typeGuard":null,"tryCatchPattern":"try:\n    model = HuggingFaceTransformersVlmModel(...)\nexcept NotImplementedError as e:\n    if 'transformers<5' in str(e):\n        vlm_options.engine = 'vllm'  # switch engine instead of downgrading shared env\n        model = None  # rebuild via the vLLM engine\n    else:\n        raise","preventionTips":["Isolate Docling VLM work in a transformers-v4 environment","Prefer the vLLM engine for dots models when transformers must stay current","Pin 'transformers>=4,<5' wherever dots models are configured"],"tags":["transformers","version-conflict","dots-ocr","vlm"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}