docling-project/docling · error · RuntimeError

{pipeline_name} does not support ThreadedDoclingParseDocumen

Error message

{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.

What it means

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.

Source

Thrown at docling/pipeline/vlm_pipeline.py:76

from docling.models.stages.vlm_convert.vlm_convert_model import VlmConvertModel
from docling.models.vlm_pipeline_models.api_vlm_model import ApiVlmModel
from docling.models.vlm_pipeline_models.hf_transformers_model import (
    HuggingFaceTransformersVlmModel,
)
from docling.models.vlm_pipeline_models.mlx_model import HuggingFaceMlxModel
from docling.pipeline.base_pipeline import PaginatedPipeline
from docling.utils.deepseekocr_utils import parse_deepseekocr_markdown
from docling.utils.profiling import ProfilingScope, TimeRecorder

_log = logging.getLogger(__name__)
_DOCLANG_OPEN_RE = re.compile(r"<doclang(?:\s[^>]*)?>")


def _raise_if_unsupported_threaded_backend(
    backend: AbstractDocumentBackend, pipeline_name: str
) -> None:
    if isinstance(backend, ThreadedDoclingParseDocumentBackend):
        raise RuntimeError(
            f"{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."
        )


class VlmPipeline(PaginatedPipeline):
    def __init__(self, pipeline_options: VlmPipelineOptions):
        super().__init__(pipeline_options)
        self.keep_backend = True
        self.pipeline_options: VlmPipelineOptions

        # Check if using new VlmConvertOptions
        if isinstance(pipeline_options.vlm_options, VlmConvertOptions):
            self._initialize_new_runtime_system(pipeline_options)
        else:
            self._initialize_legacy_vlm_models(pipeline_options)

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Use StandardPdfPipeline for inputs handled by ThreadedDoclingParseDocumentBackend.
2. Or keep VlmPipeline but disable the threaded parse backend so a classic load_page()-based backend is selected.
3. Review the format_options passed to DocumentConverter to confirm which pipeline is instantiated for InputFormat.PDF.
4. Check the pipeline's documented backend compatibility before mixing experimental backends with VLM pipelines.

Example fix

# before
pipeline = VlmPipeline(pipeline_options=VlmPipelineOptions(vlm_options=SMOLDOCLING_VLLM))
conv = DocumentConverter(format_options={InputFormat.PDF: PdfFormatOptions(pipeline_cls=...)})
# with threaded parse backend enabled -> RuntimeError

# after
converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOptions(pipeline_options=StandardPdfPipelineOptions())}
)  # let StandardPdfPipeline handle threaded parse backend

from docling.backend.docling_parse_v4_backend import ThreadedDoclingParseDocumentBackend

def vlm_safe(backend) -> bool:
    return not isinstance(backend, ThreadedDoclingParseDocumentBackend)

def is_threaded_parse_backend(backend) -> bool:
    return type(backend).__name__ == 'ThreadedDoclingParseDocumentBackend'

try:
    result = vlm_converter.convert(pdf)
except RuntimeError as e:
    if 'ThreadedDoclingParseDocumentBackend' in str(e):
        result = standard_converter.convert(pdf)  # fallback to StandardPdfPipeline

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• {pipeline_name} does not support ThreadedDoclingParseDocumen
• The selected backend {type(conv_res.input._backend).__name__
• No pipeline could be initialized for format {format}
• No pipeline could be initialized for {in_doc.file}.
• No default extraction backend configured for {fmt}

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