docling-project/docling · error · RuntimeError

Failed to convert doc (hash={self.document_hash}, name={self

Error message

Failed to convert doc (hash={self.document_hash}, name={self.file.name}).

What it means

During convert(), the USPTO parser ran but returned None, meaning it could not produce a DoclingDocument from the patent_content. The backend raises RuntimeError including the document hash and filename so the failing input can be identified in logs. Parse() returning None signals content-level failure (unrecognized structure), not an exception.

Source

Thrown at docling/backend/xml/uspto_backend.py:178

    @override
    def supports_pagination(cls) -> bool:
        return False

    @override
    def unload(self) -> None:
        return

    @classmethod
    @override
    def supported_formats(cls) -> set[InputFormat]:
        return {InputFormat.XML_USPTO}

    @override
    def convert(self) -> DoclingDocument:
        if self.parser is not None:
            doc = self.parser.parse(self.patent_content)
            if doc is None:
                raise RuntimeError(
                    f"Failed to convert doc (hash={self.document_hash}, "
                    f"name={self.file.name})."
                )
            doc.name = self.file.name or "file"
            mime_type = (
                "text/plain"
                if isinstance(self.parser, PatentUsptoGrantAps)
                else "application/xml"
            )
            doc.origin = DocumentOrigin(
                mimetype=mime_type,
                binary_hash=self.document_hash,
                filename=self.file.name or "file",
            )

            return doc
        else:
            raise RuntimeError(

View on GitHub (pinned to 61d76f1ff3)

Solutions

Use the hash/name from the message to locate the exact input file and inspect it manually.
Validate the document is a complete, well-formed patent (opens in an XML editor, ends with closing root tag).
Re-fetch the document from the source dataset.
Catch RuntimeError around conversion in batch jobs and quarantine the file for manual review.

Example fix

# before
result = converter.convert(patent_path)  # RuntimeError: Failed to convert doc

# after
try:
    result = converter.convert(patent_path)
except RuntimeError as e:
    logger.error("skipping unparseable patent %s: %s", patent_path, e)
    quarantine.append(patent_path)

Defensive patterns

Strategy: try-catch

Try / catch

try:
    doc = backend.convert()
except RuntimeError as e:
    if "Failed to convert doc" in str(e):
        logger.error("USPTO parse returned None for %s; quarantining", backend.file.name)
        return None
    raise

Prevention

Extract hash/name from the message to find the offending file in large corpora.
Verify patents are complete (closing root tag present) before batch runs.
Quarantine parse-None files for manual triage instead of aborting the batch.

When it happens

Trigger: Calling convert() on a PatentUsptoDocumentBackend whose parser matched a DOCTYPE (so parser is set) but whose body content the parser cannot handle — malformed, truncated, or a patent flavor/variant the parser doesn't cover.

Common situations: Truncated bulk USPTO downloads that keep the header but lose the body; mixed corpora where a non-patent XML got a patent DOCTYPE; parser coverage gaps on newer/older patent schema variants.

Related errors

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