docling-project/docling · error · ConversionError

Extraction failed because the provided file has no recogniza

Error message

Extraction failed because the provided file has no recognizable format or it wasn't in the list of allowed formats.

What it means

ConversionError raised by DocumentExtractor.extract() when the whole conversion/extension yields zero ExtractionResults and raises_on_error=True. Zero results means the file's format could not be recognized from its name/content, or the format is not in allowed_formats, so no pipeline ever ran.

Source

Thrown at docling/document_extractor.py:190

        had_result = False
        for ext_res in ext_res_iter:
            had_result = True
            if raises_on_error and ext_res.status not in {
                ConversionStatus.SUCCESS,
                ConversionStatus.PARTIAL_SUCCESS,
            }:
                error_details = ""
                if ext_res.errors:
                    error_messages = [err.error_message for err in ext_res.errors]
                    error_details = f" Errors: {'; '.join(error_messages)}"
                raise ConversionError(
                    f"Extraction failed for: {ext_res.input.file} with status: {ext_res.status.value}.{error_details}"
                )
            else:
                yield ext_res

        if not had_result and raises_on_error:
            raise ConversionError(
                "Extraction failed because the provided file has no recognizable format or it wasn't in the list of allowed formats."
            )

    # --------------------------- Internal engine ------------------------------

    def _extract(
        self,
        conv_input: _DocumentConversionInput,
        raises_on_error: bool,
        template: ExtractionTemplateType,
    ) -> Iterator[ExtractionResult]:
        start_time = time.monotonic()

        for input_batch in chunkify(
            conv_input.docs(self.extraction_format_to_options),
            settings.perf.doc_batch_size,
        ):
            _log.info("Going to extract document batch...")

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Give the file/DocumentStream a name with a recognized extension (e.g. '.pdf', '.png').
2. Pass allowed_formats covering the actual format, or a format_options entry that maps it to a pipeline.
3. If the format is genuinely unsupported, convert it to a supported format (PDF/image) before extraction.

Example fix

# before
stream = DocumentStream(name='download', stream=BytesIO(pdf_bytes))
extractor.extract([stream])  # no recognizable format

# after
stream = DocumentStream(name='download.pdf', stream=BytesIO(pdf_bytes))
extractor.extract([stream])

from pathlib import Path
SUPPORTED_EXTS = {'.pdf', '.png', '.jpg', '.jpeg', '.tif', '.tiff', '.bmp'}
name = stream.name if isinstance(stream, DocumentStream) else str(path)
assert Path(name).suffix.lower() in SUPPORTED_EXTS, f'unrecognizable name: {name}'

def has_recognized_extension(name: str, exts: set[str]) -> bool:
    return Path(name).suffix.lower() in exts

from docling.datamodel.base_models import ConversionError
try:
    list(extractor.extract(inputs))
except ConversionError as e:
    if 'no recognizable format' in str(e):
        for i in inputs:  # fix names/extensions, then retry
            ...

When it happens

Trigger: extractor.extract('data.xyz') where '.xyz' maps to no InputFormat; or passing allowed_formats/formats that exclude the file's actual format; or a DocumentStream whose name lacks a recognizable extension.

Common situations: Feeding extension-less temp files or wrongly-named DocumentStreams (name='tmp' instead of 'tmp.pdf'); copying the allowed_formats pattern from DocumentConverter examples but omitting the format actually being sent.

Related errors

• No default options configured for {format}
• No pipeline could be initialized for format {format}
• format {format} is not supported in `convert_string`
• 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/238302fdf38fc839. Report an issue: GitHub.