docling-project/docling · error · TypeError

DOTS JSON parsing requires VlmConvertOptions or BaseVlmOptio

Error message

DOTS JSON parsing requires VlmConvertOptions or BaseVlmOptions, got {type(vlm_options).__name__}.

What it means

When VlmPipeline._parse_dots_json parses dots.OCR JSON output, it needs the VLM scale and max_size settings, which only exist on VlmConvertOptions or BaseVlmOptions. If pipeline_options.vlm_options is some other type (or None), the required geometry settings are unavailable and a TypeError is raised naming the offending type. This guards against misconfigured or incomplete VLM options when DOTS_JSON response format is selected.

Source

Thrown at docling/pipeline/vlm_pipeline.py:594

                page_no=pg_idx + 1,
                filename=conv_res.input.file.name or "file",
                page_image=page.image,
            )
            page_docs.append(page_doc)

        return self._add_page_metadata_and_concatenate(page_docs, conv_res)

    def _parse_dots_json(self, conv_res: ConversionResult) -> DoclingDocument:
        """Parse dots.ocr / dots.mocr JSON output into a DoclingDocument."""
        from docling.utils.dots_utils import parse_dots_json
        from docling.utils.vlm_utils import compute_qwen2vl_image_size

        vlm_options = self.pipeline_options.vlm_options
        if isinstance(vlm_options, (VlmConvertOptions, BaseVlmOptions)):
            vlm_scale = vlm_options.scale
            vlm_max_size = vlm_options.max_size
        else:
            raise TypeError(
                "DOTS JSON parsing requires VlmConvertOptions or BaseVlmOptions, "
                f"got {type(vlm_options).__name__}."
            )

        page_docs = []

        for pg_idx, page in enumerate(conv_res.pages):
            predicted_text = ""
            if page.predictions.vlm_response:
                predicted_text = page.predictions.vlm_response.text

            assert page.size is not None

            inference_image = page.get_image(scale=vlm_scale, max_size=vlm_max_size)

            model_image_size = None
            if inference_image is not None:
                model_image_size = compute_qwen2vl_image_size(

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Set VlmPipelineOptions.vlm_options to a VlmConvertOptions (or BaseVlmOptions subclass) instance, e.g. a preset like the dots.OCR model options.
2. Use a DOTS-capable preset (e.g. the dots.mocr model constant) so vlm_options and response_format are configured together.
3. Ensure any custom options class subclasses BaseVlmOptions so scale/max_size are present.
4. Verify vlm_options is not None before selecting DOTS_JSON as response format.

Example fix

# before
opts = VlmPipelineOptions()  # vlm_options unset
opts.vlm_options.response_format = ResponseFormat.DOTS_JSON

# after
from docling.datamodel.pipeline_options_vlm_model import VlmConvertOptions, ResponseFormat
opts = VlmPipelineOptions(
    vlm_options=VlmConvertOptions(response_format=ResponseFormat.DOTS_JSON, scale=2.0, max_size=None)
)

from docling.datamodel.pipeline_options_vlm_model import VlmConvertOptions, BaseVlmOptions

ok = isinstance(opts.vlm_options, (VlmConvertOptions, BaseVlmOptions)) and opts.vlm_options is not None

def has_vlm_convert_options(vlm_options) -> bool:
    from docling.datamodel.pipeline_options_vlm_model import VlmConvertOptions, BaseVlmOptions
    return isinstance(vlm_options, (VlmConvertOptions, BaseVlmOptions))

try:
    result = vlm_converter.convert(doc)  # DOTS_JSON selected
except TypeError as e:
    if 'DOTS JSON parsing' in str(e):
        opts.vlm_options = VlmConvertOptions(response_format=ResponseFormat.DOTS_JSON)
        # rebuild pipeline and retry

When it happens

Trigger: Setting response_format to DOTS_JSON while vlm_options on VlmPipelineOptions is None, a plain dict, or an unrelated options class; constructing VlmPipelineOptions manually and forgetting vlm_options; subclassing VLM options in a way that drops the BaseVlmOptions base.

Common situations: Hand-rolled VlmPipelineOptions without vlm_options; deserializing options from JSON into a generic object; version upgrades where vlm_options became required for dots parsing.

Related errors

• prompt must be str or list[str], got {type(prompt)}
• Unsupported template type: {type(template)}
• Could not instantiate the right type of VLM pipeline: {vlm_o
• Unsupported input type: {type(self.path_or_stream)}
• Unexpected: {type(self.path_or_stream)=}

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