docling-project/docling · error · ValueError

Could not instantiate the right type of VLM pipeline: {vlm_o

Error message

Could not instantiate the right type of VLM pipeline: {vlm_options.inference_framework}

What it means

When VlmPipeline builds its model stack, it dispatches on vlm_options.inference_framework and knows how to construct models for a fixed set of frameworks (Transformers, vLLM, API, etc.). Reaching the else branch means the enum value does not match any supported branch, so no model can be instantiated. In practice this happens when a custom InferenceFramework value or an unknown/unsupported framework is set on the VLM options.

Source

Thrown at docling/pipeline/vlm_pipeline.py:203

                        enabled=True,
                        artifacts_path=self.artifacts_path,
                        accelerator_options=pipeline_options.accelerator_options,
                        vlm_options=vlm_options,
                    ),
                ]
            elif vlm_options.inference_framework == InferenceFramework.VLLM:
                from docling.models.vlm_pipeline_models.vllm_model import VllmVlmModel

                self.build_pipe = [
                    VllmVlmModel(
                        enabled=True,
                        artifacts_path=self.artifacts_path,
                        accelerator_options=pipeline_options.accelerator_options,
                        vlm_options=vlm_options,
                    ),
                ]
            else:
                raise ValueError(
                    f"Could not instantiate the right type of VLM pipeline: {vlm_options.inference_framework}"
                )

    def initialize_page(self, conv_res: ConversionResult, page: Page) -> Page:
        with TimeRecorder(conv_res, "page_init"):
            images_scale = self.pipeline_options.images_scale
            if images_scale is not None:
                page._default_image_scale = images_scale
            _raise_if_unsupported_threaded_backend(
                conv_res.input._backend, self.__class__.__name__
            )
            page._backend = conv_res.input._backend.load_page(page.page_no - 1)  # type: ignore
            if page._backend is not None and page._backend.is_valid():
                page.size = page._backend.get_size()

                if self.force_backend_text:
                    page.parsed_page = page._backend.get_segmented_page()

View on GitHub (pinned to 61d76f1ff3)

Solutions

Set inference_framework to a supported value from InferenceFramework in docling.datamodel.pipeline_options_vlm_model (e.g. API, TRANSFORMERS, VLLM) matching the installed docling version.
Prefer a built-in preset (e.g. SMOLDOCLING_VLLM, GRANITE_VISION_OLLAMA) over hand-built options so the framework is always consistent.
Upgrade docling to a release that supports the framework you need.
If extending InferenceFramework yourself, also patch the pipeline's build_pipe dispatch to handle the new member.

Example fix

# before
vlm_options = InlineVlmOptions(inference_framework='tensorrt', ...)  # unsupported
pipeline = VlmPipeline(VlmPipelineOptions(vlm_options=vlm_options))

# after
from docling.datamodel.pipeline_options_vlm_model import InferenceFramework
vlm_options = InlineVlmOptions(inference_framework=InferenceFramework.VLLM, ...)

Defensive patterns

Strategy: validation

Validate before calling

from docling.datamodel.pipeline_options_vlm_model import InferenceFramework

def framework_supported(fw) -> bool:
    return fw in {InferenceFramework.API, InferenceFramework.TRANSFORMERS, InferenceFramework.VLLM}

Try / catch

try:
    pipeline = VlmPipeline(options)
except ValueError as e:
    if 'inference framework' in str(e) or 'instantiate' in str(e):
        options.vlm_options.inference_framework = InferenceFramework.API

Prevention

Use built-in VLM presets whose inference_framework is guaranteed valid.
Don't mutate inference_framework on copied presets to unsupported values.
Match docling version with the framework you need.

When it happens

Trigger: Setting VlmPipelineOptions.vlm_options.inference_framework to a value outside the handled branches (e.g. a user-extended enum member or a typo string when constructing options); passing a model preset whose inference_framework was mutated after creation; running a newer vlm_options schema against older pipeline code that lacks that framework's branch.

Common situations: model_copy(deep=True) on a preset then changing inference_framework to an experimental framework the installed docling does not support; version mismatch after upgrading one half of the VLM stack; constructing InlineVlmOptions manually with a wrong framework constant.

Related errors

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