docling-project/docling · error · RuntimeError

No default extraction backend configured for {fmt}

Error message

No default extraction backend configured for {fmt}

What it means

RuntimeError thrown by the standalone DocumentExtractor's default-options helper when an extraction is requested for an InputFormat that has no default backend mapping. Only InputFormat.IMAGE and InputFormat.PDF have defaults; everything else requires the caller to supply an ExtractionFormatOption explicitly.

Source

Thrown at docling/document_extractor.py:83

            self.pipeline_options = self.pipeline_cls.get_default_options()  # type: ignore[assignment]
        return self


def _get_default_extraction_option(fmt: InputFormat) -> ExtractionFormatOption:
    """Return the default extraction option for a given input format.

    Defaults mirror the converter's *backend* choices, while the pipeline is
    the VLM extractor. This duplication will be removed when we deduplicate
    the format registry between convert/extract.
    """
    format_to_default_backend: dict[InputFormat, Type[AbstractDocumentBackend]] = {
        InputFormat.IMAGE: ImageDocumentBackend,
        InputFormat.PDF: PyPdfiumDocumentBackend,
    }

    backend = format_to_default_backend.get(fmt)
    if backend is None:
        raise RuntimeError(f"No default extraction backend configured for {fmt}")

    return ExtractionFormatOption(
        pipeline_cls=ExtractionVlmPipeline,
        backend=backend,
    )


class DocumentExtractor:
    """Standalone extractor class.

    Public API:
        - `extract(...) -> ExtractionResult`
        - `extract_all(...) -> Iterator[ExtractionResult]`

    Implementation intentionally reuses `_DocumentConversionInput` to build
    `InputDocument` with the correct backend per format.
    """

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Pass explicit format options for the format: DocumentExtractor(format_options={fmt: ExtractionFormatOption(pipeline_cls=..., backend=SomeBackend)}).
2. Convert the document to PDF or an image first with DocumentConverter, then run extraction on that.
3. Restrict extraction inputs to IMAGE/PDF, which are the only formats with defaults.

Example fix

# before
extractor = DocumentExtractor()
res = extractor.extract('page.html')  # RuntimeError: no default backend

# after
from docling.datamodel.settings import ExtractionFormatOption
opts = ExtractionFormatOption(pipeline_cls=ExtractionVlmPipeline, backend=MyHtmlBackend)
extractor = DocumentExtractor(format_options={InputFormat.HTML: opts})

from docling.datamodel.base_models import InputFormat
DEFAULT_EXTRACT_FORMATS = {InputFormat.IMAGE, InputFormat.PDF}
if fmt not in DEFAULT_EXTRACT_FORMATS and fmt not in extractor.format_to_options:
    raise SystemExit(f'{fmt} needs an explicit ExtractionFormatOption with a backend')

try:
    res = extractor.extract(path)
except RuntimeError as e:
    if 'No default extraction backend' in str(e):
        raise SystemExit('pass format_options={fmt: ExtractionFormatOption(...)} for this format')
    raise

When it happens

Trigger: Calling DocumentExtractor.extract() on a file whose format resolves to something other than IMAGE or PDF without passing a matching format_options entry with an explicit backend.

Common situations: Using the new extraction API on HTML, AsciiDoc, or Office inputs and assuming it mirrors DocumentConverter's coverage; upgrading Docling where the extractor registry (intentionally minimal) does not yet cover your format.

Related errors

• No extraction pipeline could be initialized for {in_doc.file
• The selected backend {type(conv_res.input._backend).__name__
• {pipeline_name} does not support ThreadedDoclingParseDocumen
• Unknown EBCDIC codec {encoding!r}.
• The EBCDIC backend needs a layout: set either EbcdicBackendO

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