docling-project/docling · error · NotImplementedError

Phi 4 only works with transformers<4.52.0 but you have {tran

Error message

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'

What it means

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.

Source

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

        if self.enabled:
            import torch
            from transformers import (
                AutoModel,
                AutoModelForCausalLM,
                AutoModelForImageTextToText,
                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,

View on GitHub (pinned to 61d76f1ff3)

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

Example fix

# before: transformers 4.55 installed
vlm_options.repo_id = "microsoft/Phi-4-multimodal-instruct"  # NotImplementedError
# after
# pip install -U 'transformers<4.52.0'
vlm_options.repo_id = "microsoft/Phi-4-multimodal-instruct"

Defensive patterns

Strategy: validation

Validate before calling

from packaging.version import Version
import transformers

if vlm_options.repo_id == 'microsoft/Phi-4-multimodal-instruct':
    assert Version(transformers.__version__) < Version('4.52.0'), 'Phi-4 needs transformers<4.52.0'

Try / catch

try:
    model = HuggingFaceTransformersVlmModel(...)
except NotImplementedError as e:
    if 'transformers<4.52.0' in str(e):
        raise SystemExit('Run: pip install -U \'transformers<4.52.0\'')
    raise

Prevention

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

When it happens

Trigger: 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.

Common situations: Fresh environments pulling the latest transformers; another package transitively upgrading transformers; not using docling's transformers-v4 constraints so an incompatible version slipped in.

Related errors

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