docling-project/docling · error · RuntimeError

Unsupported VLM response format {self.pipeline_options.vlm_o

Error message

Unsupported VLM response format {self.pipeline_options.vlm_options.response_format}. Only DOCTAGS format is supported.

What it means

RuntimeError safety net in ThreadedLayoutVlmPipeline's document assembly: the VLM response format must be DOCTAGS for the assembly stage to turn predictions into a document. Normally the Pydantic validator on the options class rejects other formats earlier, so hitting this means options were mutated after validation or bypassed validation.

Source

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

        # Clean up images if not needed for remaining pages
        if not self.pipeline_options.generate_page_images:
            for p in conv_res.pages:
                p._image_cache = {}

    def _assemble_document(self, conv_res: ConversionResult) -> ConversionResult:
        """Assemble final document from VLM predictions."""
        from docling_core.types.doc import DocItem, ImageRef, PictureItem

        from docling.datamodel.pipeline_options_vlm_model import ResponseFormat

        with TimeRecorder(conv_res, "doc_assemble", scope=ProfilingScope.DOCUMENT):
            # Response format validation is done in ThreadedLayoutVlmPipelineOptions
            # This check is kept as a safety net, but should never trigger if validation works
            if (
                self.pipeline_options.vlm_options.response_format
                != ResponseFormat.DOCTAGS
            ):
                raise RuntimeError(
                    f"Unsupported VLM response format {self.pipeline_options.vlm_options.response_format}. Only DOCTAGS format is supported."
                )
            conv_res.document = self._turn_dt_into_doc(conv_res)

            # Generate images of the requested element types
            if self.pipeline_options.generate_picture_images:
                # Create mapping from page_no to Page object since pages may be non-continuous
                page_map = {p.page_no: p for p in conv_res.pages}
                scale = self.pipeline_options.images_scale
                for element, _level in conv_res.document.iterate_items():
                    if not isinstance(element, DocItem) or len(element.prov) == 0:
                        continue
                    if (
                        isinstance(element, PictureItem)
                        and self.pipeline_options.generate_picture_images
                    ):
                        page_no = element.prov[0].page_no
                        page = page_map.get(page_no)

View on GitHub (pinned to 61d76f1ff3)

Solutions

Set response_format=ResponseFormat.DOCTAGS and rebuild the pipeline options object so the validator runs again.
Treat pipeline options as immutable after pipeline construction; create a new pipeline for a new configuration.
When deserializing options, round-trip through the Pydantic model (parse_obj) rather than dict patching.

Example fix

# before
pipeline.pipeline_options.vlm_options.response_format = ResponseFormat.MARKDOWN  # mutation
conv_res = pipeline(doc)

# after
from docling.datamodel.pipeline_options_vlm_model import ResponseFormat
opts = ThreadedLayoutVlmPipelineOptions(
    vlm_options=VlmOptions(response_format=ResponseFormat.DOCTAGS)
)
pipeline = ThreadedLayoutVlmPipeline(opts)

Defensive patterns

Strategy: validation

Validate before calling

from docling.datamodel.pipeline_options_vlm_model import ResponseFormat
assert pipeline.pipeline_options.vlm_options.response_format == ResponseFormat.DOCTAGS, 'rebuild options with DOCTAGS'

Try / catch

try:
    conv_res = pipeline(in_doc)
except RuntimeError as e:
    if 'Only DOCTAGS format is supported' in str(e):
        raise SystemExit('options mutated after validation; rebuild pipeline with DOCTAGS options')

Prevention

Treat pipeline options as immutable once the pipeline is constructed.
Rebuild options objects (and pipelines) on any configuration change instead of mutating fields.

When it happens

Trigger: Constructing valid options with DOCTAGS, then reassigning pipeline_options.vlm_options.response_format to MARKDOWN/JSON at runtime before conversion; or injecting options objects built with model_construct (validation skipped).

Common situations: Tweaking a shared options object between runs (e.g. toggling response_format for a markdown-side experiment) without rebuilding the pipeline; deserializing options from config without revalidation.

Related errors

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