docling-project/docling · error · ValueError

Unsupported VLM inference framework

Error message

Unsupported VLM inference framework: {vlm_options.inference_framework}

What it means

ValueError raised while building the VLM model inside ThreadedLayoutVlmPipeline: vlm_options.inference_framework is not one of the frameworks the pipeline knows how to instantiate (the elif chain covers only specific InferenceFramework members such as TRANSFORMERS and VLLM).

Solutions

Use one of the frameworks supported by the threaded pipeline, e.g. InferenceFramework.VLLM or the local transformers-based one shown in the branch above.
If you need API-based inference, use the standard VlmPipeline with StandardPdfPipeline instead.
Pin/align Docling versions so the enum values you reference match what the pipeline implements.

Example fix

# before
vlm_opts.inference_framework = InferenceFramework.API  # not implemented here

# after
vlm_opts.inference_framework = InferenceFramework.VLLM
# (or use StandardPdfPipeline + VlmPipeline for API-backed inference)

Defensive patterns

Strategy: validation

Validate before calling

from docling.datamodel.pipeline_options_vlm_model import InferenceFramework
SUPPORTED = {InferenceFramework.TRANSFORMERS, InferenceFramework.VLLM}
assert vlm_opts.inference_framework in SUPPORTED, 'threaded pipeline supports local frameworks only'

Type guard

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

Try / catch

try:
    pipeline = ThreadedLayoutVlmPipeline(opts)
except ValueError as e:
    if 'Unsupported VLM inference framework' in str(e):
        vlm_opts.inference_framework = InferenceFramework.VLLM
        pipeline = ThreadedLayoutVlmPipeline(opts)

Prevention

Restrict threaded-pipeline configs to the local inference frameworks it implements.
Keep API-framework configs paired with the standard VlmPipeline.

When it happens

Trigger: Setting ThreadedLayoutVlmPipelineOptions.vlm_options.inference_framework to a framework not handled by this pipeline (e.g. an API/remote framework enum value) and then initializing the pipeline.

Common situations: Reusing options written for the standard VlmPipeline which supports remote-API inference frameworks; enum gains new members in a newer Docling version that the experimental threaded pipeline has not adopted yet.

Related errors

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

Appendix: source

Thrown at docling/experimental/pipeline/threaded_layout_vlm_pipeline.py:208

                )
            elif vlm_options.inference_framework == InferenceFramework.MLX:
                self.vlm_model = HuggingFaceMlxModel(
                    enabled=True,
                    artifacts_path=art_path,
                    accelerator_options=self.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.vlm_model = VllmVlmModel(
                    enabled=True,
                    artifacts_path=art_path,
                    accelerator_options=self.pipeline_options.accelerator_options,
                    vlm_options=vlm_options,
                )
            else:
                raise ValueError(
                    f"Unsupported VLM inference framework: {vlm_options.inference_framework}"
                )
        else:
            raise ValueError(f"Unsupported VLM options type: {type(base_vlm_options)}")

    def _resolve_artifacts_path(self) -> Optional[Path]:
        """Resolve artifacts path from options or settings."""
        if self.pipeline_options.artifacts_path:
            p = Path(self.pipeline_options.artifacts_path).expanduser()
        elif settings.artifacts_path:
            p = Path(settings.artifacts_path).expanduser()
        else:
            return None
        if not p.is_dir():
            raise RuntimeError(
                f"{p} does not exist or is not a directory containing the required models"
            )
        return p

View on GitHub (pinned to 61d76f1ff3)