docling-project/docling · error · ConversionError

Conversion failed because the provided file has no recogniza

Error message

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

What it means

convert_all tracks whether any ConversionResult was yielded; if none was produced and raises_on_error is true, it raises ConversionError stating the file had no recognizable format or was not in the allowed formats. This happens when every input was rejected before conversion (format detection failed or the detected format is excluded by allowed_formats/format_options), so there is no per-file result to report.

Source

Thrown at docling/document_converter.py:589

                ConversionStatus.PARTIAL_SUCCESS,
            }:
                error_details = ""
                if conv_res.errors:
                    error_messages = [err.error_message for err in conv_res.errors]
                    error_details = f" Errors: {'; '.join(error_messages)}"
                # Chain the underlying exception (when one was captured during
                # input construction) so callers can classify failures via
                # ``__cause__`` — e.g. an encrypted PDF surfaces the original
                # ``PdfiumError``. See issue #1920.
                raise ConversionError(
                    f"Conversion failed for: {conv_res.input.file} with status: "
                    f"{conv_res.status.value}.{error_details}"
                ) from get_input_rejection_cause(conv_res.input)
            else:
                yield conv_res

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

    @validate_call(config=ConfigDict(strict=True))
    def convert_string(
        self,
        content: str,
        format: InputFormat,
        name: Optional[str] = None,
    ) -> ConversionResult:
        """Convert a document given as a string using the specified format.

        Only Markdown (`InputFormat.MD`), HTML (`InputFormat.HTML`), and DocLang
        (`InputFormat.XML_DOCLANG`) formats are supported. The content is wrapped
        in a `DocumentStream` and passed to the main conversion pipeline.

        Args:

View on GitHub (pinned to 61d76f1ff3)

Solutions

Pre-check the detected format with FormatToExtensions / docling's format detection and reject unsupported files with your own error message.
Widen allowed_formats / add format_options to cover the formats you actually accept.
Handle this ConversionError (or use raises_on_error=False) and report 'unsupported file type' to the user.

Example fix

# before
res = converter.convert(user_path)  # raises on unrecognized file

# after
from docling.datamodel.document import InputDocument
try:
    res = converter.convert(user_path)
except ConversionError as e:
    raise HTTPException(415, "Unsupported or unrecognized file format") from e

Defensive patterns

Strategy: try-catch

Validate before calling

from docling.datamodel.document import InputDocument
from docling.core.utils import DocumentFormatToExtension  # if available; else check suffix

def detectable(path: Path, allowed: set[InputFormat]) -> bool:
    fmt = detect_format(path)  # docling format detection
    return fmt in allowed

Try / catch

try:
    result = converter.convert(path)
except ConversionError as e:
    if "no recognizable format" in str(e):
        return unsupported_file_response(path)
    raise

Prevention

Restrict uploads by extension/MIME type before invoking the converter.
Keep allowed_formats in sync with the file types your product actually accepts.
Give users a clear 'unsupported file type' message rather than a raw ConversionError.

When it happens

Trigger: Calling convert() / convert_all() with raises_on_error=True on a file whose extension/content is unrecognized, or whose detected InputFormat is not among the converter's allowed_formats; an empty/garbage file; a misnamed extension confusing format detection.

Common situations: Uploading arbitrary user files without pre-filtering; allowed_formats narrowed to PDF while receiving images; files with wrong extensions or corrupt content.

Related errors

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