docling-project/docling · error · RuntimeError

The selected backend {type(conv_res.input._backend).__name__

Error message

The selected backend {type(conv_res.input._backend).__name__} for {conv_res.input.file} is not a paginated backend. Can not convert this with a paginated PDF pipeline. Please check your format configuration on DocumentConverter.

What it means

Paginated pipelines (StandardPdfPipeline and subclasses) build documents by iterating pages via a PaginatedDocumentBackend; _build_document asserts the input's backend is a PaginatedDocumentBackend and raises RuntimeError otherwise. It fires when a non-paginated format (HTML, MSWord, audio, image-only) is routed to a PDF-style pipeline — usually a wrong format_to_pipeline mapping in DocumentConverter.

Source

Thrown at docling/pipeline/base_pipeline.py:253

        pass


class PaginatedPipeline(ConvertPipeline):  # TODO this is a bad name.
    def __init__(self, pipeline_options: ConvertPipelineOptions):
        super().__init__(pipeline_options)
        self.keep_backend = False

    def _apply_on_pages(
        self, conv_res: ConversionResult, page_batch: Iterable[Page]
    ) -> Iterable[Page]:
        for model in self.build_pipe:
            page_batch = model(conv_res, page_batch)

        yield from page_batch

    def _build_document(self, conv_res: ConversionResult) -> ConversionResult:
        if not isinstance(conv_res.input._backend, PaginatedDocumentBackend):
            raise RuntimeError(
                f"The selected backend {type(conv_res.input._backend).__name__} for {conv_res.input.file} is not a paginated backend. "
                f"Can not convert this with a paginated PDF pipeline. "
                f"Please check your format configuration on DocumentConverter."
            )
            # conv_res.status = ConversionStatus.FAILURE
            # return conv_res

        total_elapsed_time = 0.0
        with TimeRecorder(conv_res, "doc_build", scope=ProfilingScope.DOCUMENT):
            for i in range(conv_res.input.page_count):
                start_page, end_page = conv_res.input.limits.page_range
                if (start_page - 1) <= i <= (end_page - 1):
                    conv_res.pages.append(Page(page_no=i + 1))

            try:
                total_pages_processed = 0
                # Iterate batches of pages (page_batch_size) in the doc
                for page_batch in chunkify(

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Map only paginated formats (InputFormat.PDF, possibly DOCX via PDF backend) to the paginated pipeline and use a suitable pipeline (SimplePipeline/VerticalReadingPipeline etc.) for other formats
2. If you wrote a custom backend intended for this pipeline, subclass PaginatedDocumentBackend and implement load_page/page_count
3. Check your DocumentConverter(format_to_pipeline=...) and allowed_formats — remove the mismatched entries

Example fix

# before
converter = DocumentConverter(
    allowed_formats=[InputFormat.PDF, InputFormat.HTML],
    format_to_pipeline={InputFormat.HTML: StandardPdfPipeline},
)

# after
converter = DocumentConverter(
    allowed_formats=[InputFormat.PDF, InputFormat.HTML],
)  # default routing: HTML -> SimplePipeline

from docling.datamodel.base_models import InputFormat

PAGINATED_INPUTS = {InputFormat.PDF}  # formats valid for StandardPdfPipeline
for fmt, pipe in format_to_pipeline.items():
    if pipe is StandardPdfPipeline and fmt not in PAGINATED_INPUTS:
        raise ValueError(f'{fmt} cannot use a paginated pipeline')

from docling.datamodel.document import InputDocument

def has_paginated_backend(in_doc: InputDocument) -> bool:
    from docling.datamodel.base_models import PaginatedDocumentBackend  # adjust import to version
    return isinstance(in_doc._backend, PaginatedDocumentBackend)

try:
    conv_res = converter.convert(doc)
except RuntimeError as e:
    if 'not a paginated backend' in str(e):
        log.warning('routing %s to SimplePipeline instead', doc.file.name)
        conv_res = fallback_converter.convert(doc)
    else:
        raise

When it happens

Trigger: DocumentConverter(format_to_pipeline={InputFormat.HTML: StandardPdfPipeline}) then converting an HTML file; or a custom pipeline subclass of BasePipeline/StandardPdfPipeline whose _build_document runs on a backend like AbstractDocumentBackend that has no pagination. The message names the offending backend class and file.

Common situations: Copying a pipeline mapping without trimming formats; registering StandardPdfPipeline for InputFormat.AUDIO/IMAGE; custom format backends not implementing PaginatedDocumentBackend being paired with the standard PDF pipeline.

Related errors

• The selected backend {type(conv_res.input._backend).__name__
• {pipeline_name} does not support ThreadedDoclingParseDocumen
• 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/66fa39abe0f001a9. Report an issue: GitHub.