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

RuntimeError from _raise_if_unsupported_threaded_backend: the experimental threaded layout/VLM pipelines cannot yet consume the iterator-only, out-of-order page delivery of ThreadedDoclingParseDocumentBackend; they require ordered/random page access via load_page(), which only the standard parsing backends provide.

Source

Thrown at docling/experimental/pipeline/threaded_layout_vlm_pipeline.py:66

from docling.models.vlm_pipeline_models.mlx_model import HuggingFaceMlxModel
from docling.pipeline.base_pipeline import BasePipeline
from docling.pipeline.standard_pdf_pipeline import (
    ProcessingResult,
    RunContext,
    ThreadedItem,
    ThreadedPipelineStage,
    ThreadedQueue,
)
from docling.utils.profiling import ProfilingScope, TimeRecorder

_log = logging.getLogger(__name__)


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 ThreadedLayoutVlmPipeline(BasePipeline):
    """Two-stage threaded pipeline: Layout Model → VLM Model."""

    def __init__(self, pipeline_options: ThreadedLayoutVlmPipelineOptions) -> None:
        super().__init__(pipeline_options)
        self.pipeline_options: ThreadedLayoutVlmPipelineOptions = pipeline_options
        self._run_seq = itertools.count(1)  # deterministic, monotonic run ids

        # VLM model type (initialized in _init_models)
        self.vlm_model: BaseVlmPageModel

        # Initialize models

View on GitHub (pinned to 61d76f1ff3)

Solutions

Use StandardPdfPipeline when you need ThreadedDoclingParseDocumentBackend.
Or keep ThreadedLayoutVlmPipeline but give it a conventional backend (e.g. PyPdfiumDocumentBackend) that supports load_page().
Track upstream: the restriction is expected to be lifted when the pipeline supports streamed page delivery.

Example fix

# before
pipeline = ThreadedLayoutVlmPipeline(
    opts, backend=ThreadedDoclingParseDocumentBackend(...)  # RuntimeError
)

# after
from docling.backend.pypdfium2_backend import PyPdfiumDocumentBackend
pipeline = ThreadedLayoutVlmPipeline(opts, backend=PyPdfiumDocumentBackend)
# or switch the whole conversion to StandardPdfPipeline

Defensive patterns

Strategy: type-guard

Validate before calling

from docling.backend.threaded_docling_parse_backend import ThreadedDoclingParseDocumentBackend
assert not isinstance(backend, ThreadedDoclingParseDocumentBackend), 'use StandardPdfPipeline for this backend'

Type guard

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

Try / catch

try:
    pipeline = ThreadedLayoutVlmPipeline(opts, backend=backend)
except RuntimeError as e:
    if 'ThreadedDoclingParseDocumentBackend' in str(e):
        pipeline = None  # fall back to StandardPdfPipeline configuration

Prevention

Check backend/pipeline compatibility matrix before mixing experimental components.
Prefer StandardPdfPipeline when the threaded parse backend is required.

When it happens

Trigger: Constructing ThreadedLayoutVlmPipeline (or any pipeline calling this guard) with a ThreadedDoclingParseDocumentBackend passed as the document backend.

Common situations: Mixing experimental components: enabling the threaded docling-parse backend for speed while also trying the threaded VLM pipeline; migrating a config that worked with StandardPdfPipeline.

Related errors

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