{"record":{"id":"041d4b63344b9ea2","repo":"docling-project/docling","slug":"the-selected-backend-type-conv-res-input-backend-041d4b","errorCode":null,"errorMessage":"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.","messagePattern":"The selected backend (.+?) for (.+?) is not a declarative backend\\. Can not convert this with simple pipeline\\. Please check your format configuration on DocumentConverter\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/pipeline/simple_pipeline.py","lineNumber":28,"sourceCode":"from docling.pipeline.base_pipeline import ConvertPipeline\nfrom docling.utils.profiling import ProfilingScope, TimeRecorder\n\n_log = logging.getLogger(__name__)\n\n\nclass SimplePipeline(ConvertPipeline):\n    \"\"\"SimpleModelPipeline.\n\n    This class is used at the moment for formats / backends\n    which produce straight DoclingDocument output.\n    \"\"\"\n\n    def __init__(self, pipeline_options: ConvertPipelineOptions):\n        super().__init__(pipeline_options)\n\n    def _build_document(self, conv_res: ConversionResult) -> ConversionResult:\n        if not isinstance(conv_res.input._backend, DeclarativeDocumentBackend):\n            raise RuntimeError(\n                f\"The selected backend {type(conv_res.input._backend).__name__} for {conv_res.input.file} is not a declarative backend. \"\n                f\"Can not convert this with simple pipeline. \"\n                f\"Please check your format configuration on DocumentConverter.\"\n            )\n            # conv_res.status = ConversionStatus.FAILURE\n            # return conv_res\n\n        # Instead of running a page-level pipeline to build up the document structure,\n        # the backend is expected to be of type DeclarativeDocumentBackend, which can output\n        # a DoclingDocument straight.\n        with TimeRecorder(conv_res, \"doc_build\", scope=ProfilingScope.DOCUMENT):\n            conv_res.document = conv_res.input._backend.convert()\n        return conv_res\n\n    def _determine_status(self, conv_res: ConversionResult) -> ConversionStatus:\n        # This is called only if the previous steps didn't raise.\n        # Since we don't have anything else to evaluate, we can\n        # safely return SUCCESS.","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/pipeline/simple_pipeline.py#L10-L46","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconverter = DocumentConverter(\n    format_options={InputFormat.HTML: PdfFormatOptions()},  # wrong pipeline wiring\n)\ndoc = converter.convert(Path('page.pdf'))  # RuntimeError\n\n// after\nfrom docling.pipeline.simple_pipeline import SimplePipeline\nfrom docling.pipeline.standard_pdf_pipeline import StandardPdfPipeline\n\npipeline_dict = {\n    InputFormat.PDF: StandardPdfPipeline,\n    InputFormat.HTML: SimplePipeline,  # HTML backend is declarative\n}\nconverter = DocumentConverter(format_options={f: PipelineOptions() for f in pipeline_dict})","handlingStrategy":"validation","validationCode":"from docling.datamodel.base_input import DocumentInput\nfrom docling.datamodel.document import InputDocument\n\ndef backend_is_declarative(input_doc: InputDocument) -> bool:\n    from docling.backend.document_backend import DeclarativeDocumentBackend\n    return isinstance(input_doc._backend, DeclarativeDocumentBackend)","typeGuard":null,"tryCatchPattern":"try:\n    result = converter.convert(path)\nexcept RuntimeError as e:\n    if 'not a declarative backend' in str(e):\n        # fix format->pipeline mapping in DocumentConverter\n        ...","preventionTips":["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."],"tags":["pipeline","backend","configuration","format"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}