{"record":{"id":"f73edbbc5a8e8b5c","repo":"docling-project/docling","slug":"pipeline-name-does-not-support-threadeddoclingpa-f73edb","errorCode":null,"errorMessage":"{pipeline_name} does not support ThreadedDoclingParseDocumentBackend yet. It still requires ordered/random page access via load_page() and cannot consume iterator-only or out-of-order page delivery. Use StandardPdfPipeline instead.","messagePattern":"(.+?) does not support ThreadedDoclingParseDocumentBackend yet\\. It still requires ordered/random page access via load_page\\(\\) and cannot consume iterator-only or out-of-order page delivery\\. Use StandardPdfPipeline instead\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/pipeline/vlm_pipeline.py","lineNumber":76,"sourceCode":"from docling.models.stages.vlm_convert.vlm_convert_model import VlmConvertModel\nfrom docling.models.vlm_pipeline_models.api_vlm_model import ApiVlmModel\nfrom docling.models.vlm_pipeline_models.hf_transformers_model import (\n    HuggingFaceTransformersVlmModel,\n)\nfrom docling.models.vlm_pipeline_models.mlx_model import HuggingFaceMlxModel\nfrom docling.pipeline.base_pipeline import PaginatedPipeline\nfrom docling.utils.deepseekocr_utils import parse_deepseekocr_markdown\nfrom docling.utils.profiling import ProfilingScope, TimeRecorder\n\n_log = logging.getLogger(__name__)\n_DOCLANG_OPEN_RE = re.compile(r\"<doclang(?:\\s[^>]*)?>\")\n\n\ndef _raise_if_unsupported_threaded_backend(\n    backend: AbstractDocumentBackend, pipeline_name: str\n) -> None:\n    if isinstance(backend, ThreadedDoclingParseDocumentBackend):\n        raise RuntimeError(\n            f\"{pipeline_name} does not support ThreadedDoclingParseDocumentBackend yet. \"\n            \"It still requires ordered/random page access via load_page() and cannot \"\n            \"consume iterator-only or out-of-order page delivery. Use StandardPdfPipeline instead.\"\n        )\n\n\nclass VlmPipeline(PaginatedPipeline):\n    def __init__(self, pipeline_options: VlmPipelineOptions):\n        super().__init__(pipeline_options)\n        self.keep_backend = True\n        self.pipeline_options: VlmPipelineOptions\n\n        # Check if using new VlmConvertOptions\n        if isinstance(pipeline_options.vlm_options, VlmConvertOptions):\n            self._initialize_new_runtime_system(pipeline_options)\n        else:\n            self._initialize_legacy_vlm_models(pipeline_options)\n","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/pipeline/vlm_pipeline.py#L58-L94","documentation":"VlmPipeline (and other paginated pipelines guarded by _raise_if_unsupported_threaded_backend) requires ordered/random access to pages via backend.load_page(). ThreadedDoclingParseDocumentBackend instead streams pages through an iterator and may deliver them out of order, which these pipelines cannot consume. During initialize_page the guard detects this backend type and raises immediately with a pointer to StandardPdfPipeline, which does support it.","triggerScenarios":"Constructing VlmPipeline (or the threaded VLM experimental pipeline classes calling the same guard) over an input whose backend is ThreadedDoclingParseDocumentBackend, e.g. PDF input with the threaded parse backend enabled; calling initialize_page on such a combination during conversion.","commonSituations":"Enabling the threaded/docling-parse backend option while explicitly using VlmPipeline instead of letting DocumentConverter pick StandardPdfPipeline; advanced format configuration copied from a threaded-parse example but combined with VLM options; upgrading to a docling version that introduced ThreadedDoclingParseDocumentBackend.","solutions":["Use StandardPdfPipeline for inputs handled by ThreadedDoclingParseDocumentBackend.","Or keep VlmPipeline but disable the threaded parse backend so a classic load_page()-based backend is selected.","Review the format_options passed to DocumentConverter to confirm which pipeline is instantiated for InputFormat.PDF.","Check the pipeline's documented backend compatibility before mixing experimental backends with VLM pipelines."],"exampleFix":"# before\npipeline = VlmPipeline(pipeline_options=VlmPipelineOptions(vlm_options=SMOLDOCLING_VLLM))\nconv = DocumentConverter(format_options={InputFormat.PDF: PdfFormatOptions(pipeline_cls=...)})\n# with threaded parse backend enabled -> RuntimeError\n\n# after\nconverter = DocumentConverter(\n    format_options={InputFormat.PDF: PdfFormatOptions(pipeline_options=StandardPdfPipelineOptions())}\n)  # let StandardPdfPipeline handle threaded parse backend","handlingStrategy":"type-guard","validationCode":"from docling.backend.docling_parse_v4_backend import ThreadedDoclingParseDocumentBackend\n\ndef vlm_safe(backend) -> bool:\n    return not isinstance(backend, ThreadedDoclingParseDocumentBackend)","typeGuard":"def is_threaded_parse_backend(backend) -> bool:\n    return type(backend).__name__ == 'ThreadedDoclingParseDocumentBackend'","tryCatchPattern":"try:\n    result = vlm_converter.convert(pdf)\nexcept RuntimeError as e:\n    if 'ThreadedDoclingParseDocumentBackend' in str(e):\n        result = standard_converter.convert(pdf)  # fallback to StandardPdfPipeline","preventionTips":["Use StandardPdfPipeline when the threaded parse backend is enabled.","Check pipeline/backend compatibility matrix in docs before mixing experimental features.","Don't force VlmPipeline in format options when threaded parsing is desired."],"tags":["pipeline","vlm","backend","threading","configuration"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}