{"record":{"id":"702ad053b90ee6c0","repo":"docling-project/docling","slug":"dots-json-parsing-requires-vlmconvertoptions-or-ba","errorCode":null,"errorMessage":"DOTS JSON parsing requires VlmConvertOptions or BaseVlmOptions, got {type(vlm_options).__name__}.","messagePattern":"DOTS JSON parsing requires VlmConvertOptions or BaseVlmOptions, got (.+?)\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"docling/pipeline/vlm_pipeline.py","lineNumber":594,"sourceCode":"                page_no=pg_idx + 1,\n                filename=conv_res.input.file.name or \"file\",\n                page_image=page.image,\n            )\n            page_docs.append(page_doc)\n\n        return self._add_page_metadata_and_concatenate(page_docs, conv_res)\n\n    def _parse_dots_json(self, conv_res: ConversionResult) -> DoclingDocument:\n        \"\"\"Parse dots.ocr / dots.mocr JSON output into a DoclingDocument.\"\"\"\n        from docling.utils.dots_utils import parse_dots_json\n        from docling.utils.vlm_utils import compute_qwen2vl_image_size\n\n        vlm_options = self.pipeline_options.vlm_options\n        if isinstance(vlm_options, (VlmConvertOptions, BaseVlmOptions)):\n            vlm_scale = vlm_options.scale\n            vlm_max_size = vlm_options.max_size\n        else:\n            raise TypeError(\n                \"DOTS JSON parsing requires VlmConvertOptions or BaseVlmOptions, \"\n                f\"got {type(vlm_options).__name__}.\"\n            )\n\n        page_docs = []\n\n        for pg_idx, page in enumerate(conv_res.pages):\n            predicted_text = \"\"\n            if page.predictions.vlm_response:\n                predicted_text = page.predictions.vlm_response.text\n\n            assert page.size is not None\n\n            inference_image = page.get_image(scale=vlm_scale, max_size=vlm_max_size)\n\n            model_image_size = None\n            if inference_image is not None:\n                model_image_size = compute_qwen2vl_image_size(","sourceCodeStart":576,"sourceCodeEnd":612,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/pipeline/vlm_pipeline.py#L576-L612","documentation":"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.","triggerScenarios":"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.","commonSituations":"Hand-rolled VlmPipelineOptions without vlm_options; deserializing options from JSON into a generic object; version upgrades where vlm_options became required for dots parsing.","solutions":["Set VlmPipelineOptions.vlm_options to a VlmConvertOptions (or BaseVlmOptions subclass) instance, e.g. a preset like the dots.OCR model options.","Use a DOTS-capable preset (e.g. the dots.mocr model constant) so vlm_options and response_format are configured together.","Ensure any custom options class subclasses BaseVlmOptions so scale/max_size are present.","Verify vlm_options is not None before selecting DOTS_JSON as response format."],"exampleFix":"# before\nopts = VlmPipelineOptions()  # vlm_options unset\nopts.vlm_options.response_format = ResponseFormat.DOTS_JSON\n\n# after\nfrom docling.datamodel.pipeline_options_vlm_model import VlmConvertOptions, ResponseFormat\nopts = VlmPipelineOptions(\n    vlm_options=VlmConvertOptions(response_format=ResponseFormat.DOTS_JSON, scale=2.0, max_size=None)\n)","handlingStrategy":"type-guard","validationCode":"from docling.datamodel.pipeline_options_vlm_model import VlmConvertOptions, BaseVlmOptions\n\nok = isinstance(opts.vlm_options, (VlmConvertOptions, BaseVlmOptions)) and opts.vlm_options is not None","typeGuard":"def has_vlm_convert_options(vlm_options) -> bool:\n    from docling.datamodel.pipeline_options_vlm_model import VlmConvertOptions, BaseVlmOptions\n    return isinstance(vlm_options, (VlmConvertOptions, BaseVlmOptions))","tryCatchPattern":"try:\n    result = vlm_converter.convert(doc)  # DOTS_JSON selected\nexcept TypeError as e:\n    if 'DOTS JSON parsing' in str(e):\n        opts.vlm_options = VlmConvertOptions(response_format=ResponseFormat.DOTS_JSON)\n        # rebuild pipeline and retry","preventionTips":["Always set VlmPipelineOptions.vlm_options when using DOTS_JSON.","Use DOTS presets so vlm_options and response_format are configured together."],"tags":["vlm","dots","options","type-error"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}