docling-project/docling · error · RuntimeError

Unsupported VLM response format {response_format_legacy}

Error message

Unsupported VLM response format {response_format_legacy}

What it means

After the VLM generates a response, VlmPipeline._build_document dispatches on the legacy response_format to pick a parser: Markdown, DocTags, HTML, Chandra-HTML, or DOTS JSON. If the value matches none of these branches the pipeline cannot interpret the model output and raises this RuntimeError. It indicates a response format that this docling release does not know how to parse.

Source

Thrown at docling/pipeline/vlm_pipeline.py:320

            elif response_format_legacy == ResponseFormat.MARKDOWN:
                conv_res.document = self._convert_text_with_backend(
                    conv_res, InputFormat.MD, MarkdownDocumentBackend
                )

            elif response_format_legacy == ResponseFormat.HTML:
                conv_res.document = self._convert_text_with_backend(
                    conv_res, InputFormat.HTML, HTMLDocumentBackend
                )

            elif response_format_legacy == ResponseFormat.CHANDRA_HTML:
                conv_res.document = self._parse_chandra_html(conv_res)

            elif response_format_legacy == ResponseFormat.DOTS_JSON:
                conv_res.document = self._parse_dots_json(conv_res)

            else:
                raise RuntimeError(
                    f"Unsupported VLM response format {response_format_legacy}"
                )

            # Generate images of the requested element types
            if self.pipeline_options.generate_picture_images:
                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_ix = element.prov[0].page_no - 1
                        page = conv_res.pages[page_ix]
                        assert page.size is not None
                        assert page.image is not None

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Set response_format to one of the supported values for your docling version (MARKDOWN, DOCTAGS, HTML, CHANDRA_HTML, DOTS_JSON).
2. Upgrade docling to the release that supports the response format you want.
3. Use a stock VLM preset instead of custom options so response format and parser stay in sync.
4. Check the changelog for the ResponseFormat enum to see which members your version parses.

Example fix

# before
vlm_options.response_format = ResponseFormat.MOCR_JSON  # not in dispatch

# after
from docling.datamodel.pipeline_options_vlm_model import ResponseFormat
vlm_options.response_format = ResponseFormat.DOTS_JSON  # supported parser exists

from docling.datamodel.pipeline_options_vlm_model import ResponseFormat

SUPPORTED = {ResponseFormat.MARKDOWN, ResponseFormat.DOCTAGS, ResponseFormat.HTML,
             ResponseFormat.CHANDRA_HTML, ResponseFormat.DOTS_JSON}
assert vlm_options.response_format in SUPPORTED

try:
    result = vlm_converter.convert(doc)
except RuntimeError as e:
    if 'Unsupported VLM response format' in str(e):
        vlm_options.response_format = ResponseFormat.MARKDOWN
        result = vlm_converter.convert(doc)

When it happens

Trigger: Setting VlmOptions response format to a new/unrecognized ResponseFormat member (or a raw string coerced into the enum) not covered by the dispatch; upgrading options objects that carry a response format introduced in a newer docling while running older pipeline code; custom presets with response_format mutated to an experimental value.

Common situations: Using a dots.mocr or chandra-html variant before/after the release that added its parser; hand-editing serialized pipeline options JSON; mixing docling versions between the client that builds options and the process that runs conversion.

Related errors

• Unsupported VLM inference framework: {vlm_options.inference_
• {p} does not exist or is not a directory containing the requ
• Invalid metadata response from {self.model_metadata_url}: {e
• Model '{repo_id}' not found in artifacts_path. Expected loca
• Unknown prompt style: {prompt_style}. Valid values are {', '

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