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 declarative backend. Can not convert this with simple pipeline. Please check your format configuration on DocumentConverter.

What it means

SimplePipeline only works with backends that subclass DeclarativeDocumentBackend, i.e. backends that emit a complete DoclingDocument directly (MS Word, AsciiDoc, HTML, Markdown, etc.). Before calling backend.convert() the pipeline verifies the input format resolved to a declarative backend and raises this RuntimeError otherwise. It almost always means the DocumentConverter's format configuration mapped the file to a paginated backend (e.g. a PDF backend) while the format was routed through the simple pipeline.

Source

Thrown at docling/pipeline/simple_pipeline.py:28

from docling.pipeline.base_pipeline import ConvertPipeline
from docling.utils.profiling import ProfilingScope, TimeRecorder

_log = logging.getLogger(__name__)


class SimplePipeline(ConvertPipeline):
    """SimpleModelPipeline.

    This class is used at the moment for formats / backends
    which produce straight DoclingDocument output.
    """

    def __init__(self, pipeline_options: ConvertPipelineOptions):
        super().__init__(pipeline_options)

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

        # Instead of running a page-level pipeline to build up the document structure,
        # the backend is expected to be of type DeclarativeDocumentBackend, which can output
        # a DoclingDocument straight.
        with TimeRecorder(conv_res, "doc_build", scope=ProfilingScope.DOCUMENT):
            conv_res.document = conv_res.input._backend.convert()
        return conv_res

    def _determine_status(self, conv_res: ConversionResult) -> ConversionStatus:
        # This is called only if the previous steps didn't raise.
        # Since we don't have anything else to evaluate, we can
        # safely return SUCCESS.

View on GitHub (pinned to 61d76f1ff3)

Solutions

Check the format-to-pipeline map passed to DocumentConverter and give the offending InputFormat a StandardPdfPipeline (or another paginated pipeline) instead of SimplePipeline.
Verify the input file extension actually matches the intended InputFormat (e.g. don't send .pdf through a format handled by SimplePipeline).
If you wrote a custom backend, make it subclass DeclarativeDocumentBackend and implement convert() returning a DoclingDocument.
Inspect type(conv_res.input._backend) in a debugger or log conv_res.input.format to see which backend was actually selected.

Example fix

// before
converter = DocumentConverter(
    format_options={InputFormat.HTML: PdfFormatOptions()},  # wrong pipeline wiring
)
doc = converter.convert(Path('page.pdf'))  # RuntimeError

// after
from docling.pipeline.simple_pipeline import SimplePipeline
from docling.pipeline.standard_pdf_pipeline import StandardPdfPipeline

pipeline_dict = {
    InputFormat.PDF: StandardPdfPipeline,
    InputFormat.HTML: SimplePipeline,  # HTML backend is declarative
}
converter = DocumentConverter(format_options={f: PipelineOptions() for f in pipeline_dict})

Defensive patterns

Strategy: validation

Validate before calling

from docling.datamodel.base_input import DocumentInput
from docling.datamodel.document import InputDocument

def backend_is_declarative(input_doc: InputDocument) -> bool:
    from docling.backend.document_backend import DeclarativeDocumentBackend
    return isinstance(input_doc._backend, DeclarativeDocumentBackend)

Try / catch

try:
    result = converter.convert(path)
except RuntimeError as e:
    if 'not a declarative backend' in str(e):
        # fix format->pipeline mapping in DocumentConverter
        ...

Prevention

Map each InputFormat to a pipeline whose backend type matches (simple pipeline = declarative backends only).
Run a tiny smoke conversion for each configured format at startup to catch wiring mistakes early.
Custom backends destined for SimplePipeline must subclass DeclarativeDocumentBackend.

When it happens

Trigger: Building a DocumentConverter with a format_filters/pipeline assignment that pairs a format with SimplePipeline while the registered backend for that extension is not declarative; passing a PDF or image file to a converter configured with a simple-pipeline-based InputFormat; custom plugin backends that do not extend DeclarativeDocumentBackend being selected for a simple-pipeline format.

Common situations: Copy-pasting a DocumentConverter setup for 'docx' and feeding it a PDF; registering a custom backend in FORMAT_EXTENSIONS or a FormatToExtensions mapping without making it declarative; mixing up InputFormat entries when constructing the pipeline dictionary passed to DocumentConverter.

Related errors

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