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

ExtractionVlmPipeline (and other extraction pipelines using _raise_if_unsupported_threaded_backend) require ordered/random page access through backend.load_page(); the ThreadedDoclingParseDocumentBackend delivers pages iterator-only and possibly out-of-order, which extraction models cannot consume. Passing that backend raises RuntimeError immediately, directing users to StandardPdfPipeline.

Source

Thrown at docling/pipeline/extraction_vlm_pipeline.py:43

from docling.datamodel.pipeline_options import (
    PipelineOptions,
    VlmExtractionPipelineOptions,
)
from docling.datamodel.settings import settings
from docling.models.extraction.transformers_extraction_model import (
    TransformersExtractionModel,
)
from docling.pipeline.base_extraction_pipeline import BaseExtractionPipeline
from docling.utils.accelerator_utils import decide_device

_log = logging.getLogger(__name__)


def _raise_if_unsupported_threaded_backend(
    backend: PaginatedDocumentBackend, 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 ExtractionVlmPipeline(BaseExtractionPipeline):
    def __init__(self, pipeline_options: VlmExtractionPipelineOptions):
        super().__init__(pipeline_options)

        self.accelerator_options = pipeline_options.accelerator_options
        self.pipeline_options: VlmExtractionPipelineOptions

        self.vlm_model = TransformersExtractionModel(
            enabled=True,
            artifacts_path=self.artifacts_path,
            accelerator_options=self.accelerator_options,
            vlm_options=pipeline_options.vlm_options,

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Use StandardPdfPipeline with ThreadedDoclingParseDocumentBackend, or ExtractionVlmPipeline with the standard (non-threaded) docling-parse backend
2. Remove/adjust the format_to_pipeline or backend selection so extraction pipelines get a regular PaginatedDocumentBackend
3. Track docling releases: retry ExtractionVlmPipeline with the threaded backend once ordered page access is implemented

Example fix

# before
format_to_pipeline = {
    InputFormat.PDF: ExtractionVlmPipeline,  # + threaded docling-parse backend
}

# after
format_to_pipeline = {
    InputFormat.PDF: StandardPdfPipeline,  # threaded backend OK here
}

from docling.datamodel.base_models import InputFormat
from docling.pipeline.extraction_vlm_pipeline import ExtractionVlmPipeline

# do not pair the threaded docling-parse backend with extraction pipelines
if any(pipe is ExtractionVlmPipeline for pipe in format_to_pipeline.values()):
    assert 'threaded' not in str(backend_choice).lower(), 'extraction pipelines need StandardPdfPipeline for threaded parsing'

try:
    converter = DocumentConverter(format_to_pipeline=...)
except RuntimeError as e:
    if 'ThreadedDoclingParseDocumentBackend' in str(e):
        # switch mapping: extraction -> standard (non-threaded) backend, or use StandardPdfPipeline
        ...

When it happens

Trigger: Configuring DocumentConverter with ExtractionVlmPipeline (VLM extraction) for PDFs while the format_to_pipeline mapping (or docling-parse threaded setup) selects ThreadedDoclingParseDocumentBackend — e.g. reusing a mapping intended for throughput-optimized standard conversion.

Common situations: Enabling threaded parsing for speed and then switching the pipeline to VLM extraction; custom format_to_pipeline entries copied from performance-tuned configs; newer docling versions exposing the threaded backend where old configs silently picked it.

Related errors

• Unsupported template type: {type(template)}
• ThreadedDoclingParseDocumentBackend only supports iter_pages
• The parameters vlm_pipeline_model, vlm_pipeline_model_local
• Cannot specify both vlm_pipeline_preset and vlm_pipeline_cus
• Cannot mix legacy VLM options (vlm_pipeline_model*) with new

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