{"record":{"id":"a45a6f7cfbc5eada","repo":"docling-project/docling","slug":"phi-4-only-works-with-transformers-4-52-0-but-you-a45a6f","errorCode":null,"errorMessage":"Phi 4 only works with transformers<4.52.0 but you have {transformers_version=}. Please downgrade by running: pip install -U 'transformers<4.52.0'","messagePattern":"Phi 4 only works with transformers<4\\.52\\.0 but you have (.+?)\\. Please downgrade by running: pip install -U 'transformers<4\\.52\\.0'","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"docling/models/vlm_pipeline_models/hf_transformers_model.py","lineNumber":80,"sourceCode":"\n        if self.enabled:\n            import torch\n            from transformers import (\n                AutoModel,\n                AutoModelForCausalLM,\n                AutoModelForImageTextToText,\n                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,","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/vlm_pipeline_models/hf_transformers_model.py#L62-L98","documentation":"HuggingFaceTransformersVlmModel checks the installed transformers version at init: microsoft/Phi-4-multimodal-instruct is known to be broken with transformers>=4.52.0 under this engine, so Docling raises NotImplementedError with the exact downgrade command instead of letting generation fail mysteriously later.","triggerScenarios":"Setting vlm_options.repo_id='microsoft/Phi-4-multimodal-instruct' with the Transformers engine while the installed transformers is >= 4.52.0, checked via importlib.metadata at model construction.","commonSituations":"Fresh environments pulling the latest transformers; another package transitively upgrading transformers; not using docling's transformers-v4 constraints so an incompatible version slipped in.","solutions":["Downgrade: pip install -U 'transformers<4.52.0'","Recreate the environment with docling's transformers-v4 extra/constraints so compatible pins are applied","If you must stay on newer transformers, pick a different VLM repo_id that supports it, or use the vLLM engine for Phi-4"],"exampleFix":"# before: transformers 4.55 installed\nvlm_options.repo_id = \"microsoft/Phi-4-multimodal-instruct\"  # NotImplementedError\n# after\n# pip install -U 'transformers<4.52.0'\nvlm_options.repo_id = \"microsoft/Phi-4-multimodal-instruct\"","handlingStrategy":"validation","validationCode":"from packaging.version import Version\nimport transformers\n\nif vlm_options.repo_id == 'microsoft/Phi-4-multimodal-instruct':\n    assert Version(transformers.__version__) < Version('4.52.0'), 'Phi-4 needs transformers<4.52.0'","typeGuard":null,"tryCatchPattern":"try:\n    model = HuggingFaceTransformersVlmModel(...)\nexcept NotImplementedError as e:\n    if 'transformers<4.52.0' in str(e):\n        raise SystemExit('Run: pip install -U \\'transformers<4.52.0\\'')\n    raise","preventionTips":["Use docling's transformers-v4 constraints file when creating envs for VLM work","Pin transformers explicitly in requirements for Phi-4 deployments","Add a CI check comparing repo_id against the installed transformers version"],"tags":["transformers","version-conflict","phi-4","vlm"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}