docling-project/docling · error · ValueError

Unsupported VLM options type: {type(base_vlm_options)}

Error message

Unsupported VLM options type: {type(base_vlm_options)}

What it means

ValueError raised in ThreadedLayoutVlmPipeline's VLM-model setup when the base VLM options object passed via pipeline_options.vlm_options is not the options type this pipeline expects. The pipeline needs to downcast to a concrete options class to read model settings; an unexpected type means configuration was mixed between pipeline families.

Source

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

                    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

    def _create_run_ctx(self) -> RunContext:
        """Create pipeline stages and wire them together."""
        opts = self.pipeline_options

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Pass the exact VLM options type required by ThreadedLayoutVlmPipelineOptions (see its field annotation / the isinstance checks in the model factory).
2. Construct fresh vlm_options per pipeline instead of reusing a global config object.
3. If your options target the standard VLM flow, switch to StandardPdfPipeline with VlmPipeline rather than the threaded pipeline.

Example fix

# before
shared = StandardVlmOptions(model_name='...')  # wrong family
opts = ThreadedLayoutVlmPipelineOptions(vlm_options=shared)

# after
from docling.datamodel.pipeline_options_vlm_model import VlmOptions
opts = ThreadedLayoutVlmPipelineOptions(
    vlm_options=VlmOptions(model_name='...', response_format=ResponseFormat.DOCTAGS)
)

from docling.experimental.datamodel.threaded_layout_vlm_pipeline_options import ThreadedLayoutVlmPipelineOptions
assert isinstance(pipeline_opts, ThreadedLayoutVlmPipelineOptions), 'wrong options class for this pipeline'

def is_threaded_options(obj) -> bool:
    return isinstance(obj, ThreadedLayoutVlmPipelineOptions)

try:
    pipeline = ThreadedLayoutVlmPipeline(opts)
except ValueError as e:
    if 'Unsupported VLM options type' in str(e):
        raise SystemExit('build fresh ThreadedLayoutVlmPipelineOptions; do not reuse standard-pipeline options')

When it happens

Trigger: Assigning a generic or different-family VlmOptions subclass (e.g. options written for the standard VlmPipeline or an API-specific options class) to ThreadedLayoutVlmPipelineOptions.vlm_options.

Common situations: Sharing one options object across standard and experimental pipelines; upgrading Docling and the expected concrete options class changed name/shape.

Related errors

• ThreadedLayoutVlmPipeline only supports DOCTAGS response for
• Expected AutoInlineVlmEngineOptions, got {type(options)}
• Expected TransformersVlmEngineOptions, got {type(options)}
• Expected MlxVlmEngineOptions, got {type(options)}
• Expected VllmVlmEngineOptions, got {type(options)}

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