docling-project/docling · error · RuntimeError

Incompatible file format {self.input_format} was passed to a

Error message

Incompatible file format {self.input_format} was passed to a PdfDocumentBackend. Valid format are {','.join(self.supported_formats())}.

What it means

RuntimeError raised by PdfDocumentBackend.__init__ when the InputDocument's format is not in the concrete backend's supported_formats(). It is an internal dispatch assertion: e.g. a PdfDocumentBackend subclass receiving InputFormat.AUDIO or DOCX means format routing is misconfigured.

Source

Thrown at docling/backend/pdf_backend.py:74

        pass


class PdfDocumentBackend(PaginatedDocumentBackend):
    supports_random_page_access: ClassVar[bool] = True

    def __init__(
        self,
        in_doc: InputDocument,
        path_or_stream: Union[BytesIO, Path],
        options: Optional[PdfBackendOptions] = None,
    ):
        if options is None:
            options = PdfBackendOptions()
        super().__init__(in_doc, path_or_stream, options)
        self.options: PdfBackendOptions

        if self.input_format not in self.supported_formats():
            raise RuntimeError(
                f"Incompatible file format {self.input_format} was passed to a PdfDocumentBackend. Valid format are {','.join(self.supported_formats())}."
            )

    @abstractmethod
    def load_page(self, page_no: int) -> PdfPageBackend:
        pass

    @abstractmethod
    def page_count(self) -> int:
        pass

    def iter_pages(self) -> Iterator[PdfPageBackend]:
        for page_index in range(self.page_count()):
            yield self.load_page(page_index)

    def get_document_outline(self) -> list[_PdfOutlineItem]:
        """Return the PDF bookmark / table-of-contents outline.

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Use the standard backend-selection path (DocumentConverter / _get_backend) instead of instantiating PdfDocumentBackend subclasses directly.
2. Filter inputs by InputFormat.PDF before routing to a PDF backend.
3. If writing a custom backend, verify supported_formats() overlaps the dispatched format.

Example fix

# before
backend = PyPdfiumDocumentBackend(in_doc, path)  # RuntimeError for non-PDF input

# after
from docling.datamodel.base_models import InputFormat
if in_doc.format == InputFormat.PDF:
    backend = PyPdfiumDocumentBackend(in_doc, path)

from docling.datamodel.base_models import InputFormat
if in_doc.format not in backend.supported_formats():
    raise ValueError(f'{in_doc.format} unsupported by {type(backend).__name__}')

def accepts(backend_cls, in_doc) -> bool:
    return in_doc.format in backend_cls.supported_formats()

if in_doc.format not in type(backend).supported_formats():
    backend = select_backend_for(in_doc)  # route to correct backend
result = backend.convert()

When it happens

Trigger: Constructing any PdfDocumentBackend subclass (pypdfium2, docling-parse, etc.) with an InputDocument whose input_format is not PDF/Image — typically when user code instantiates a backend manually instead of via the format-based backend factory.

Common situations: Custom pipelines that hard-code a PDF backend while feeding mixed-format InputDocuments; tests that reuse one fixture across formats; forks that add formats without updating the factory.

Related errors

• docling-parse could not load document {self.document_hash}:
• docling-parse could not load document {self.document_hash}.
• ThreadedDoclingParseDocumentBackend only supports iter_pages
• An internal error has occurred during Markdown conversion.
• pypdfium could not load document with hash {self.document_ha

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