docling-project/docling · error · RuntimeError

Cannot convert doc (hash={self.document_hash}, name={self.fi

Error message

Cannot convert doc (hash={self.document_hash}, name={self.file.name}) because the backend failed to init.

What it means

convert() was called while self.parser is None — the backend never matched a '<!DOCTYPE' or 'PATN' line during init, so it does not know which patent parser to use. This happens when format detection accepted the file (e.g. forced InputFormat) but the content has no recognizable USPTO header. Raised as RuntimeError with hash and filename.

Source

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

                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(
                f"Cannot convert doc (hash={self.document_hash}, "
                f"name={self.file.name}) because the backend failed to init."
            )


class PatentUspto(ABC):
    """Parser of patent documents from the US Patent Office."""

    @abstractmethod
    def parse(self, patent_content: str) -> DoclingDocument | None:
        """Parse a USPTO patent.

        Parameters:
            patent_content: The content of a single patent in a USPTO file.

        Returns:
            The patent parsed as a docling document.
        """

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Check the file's first lines: it must start with <!DOCTYPE us-patent-...> or the exact line 'PATN' (LF).
2. Normalize line endings to LF and strip any BOM before converting.
3. Don't force InputFormat.XML_USPTO for non-patent files; let DocumentConverter detect the format.
4. Catch this RuntimeError in batch jobs and route the file to the generic XML backend.

Example fix

# before
result = converter.convert(Path("patent.txt"))  # CRLF file, PATN line not matched

# after
text = Path("patent.txt").read_text().lstrip("\ufeff").replace("\r\n", "\n")
from io import BytesIO
result = converter.convert(BytesIO(text.encode("utf-8")))

from pathlib import Path

def has_uspto_header(path: Path) -> bool:
    with open(path, encoding="utf-8", errors="replace") as f:
        first = f.readline().rstrip("\r\n")
    return first.startswith("<!DOCTYPE") or first == "PATN"

try:
    doc = backend.convert()
except RuntimeError as e:
    if "failed to init" in str(e):
        raise ValueError("no USPTO DOCTYPE/PATN header found; wrong format?") from e
    raise

When it happens

Trigger: Constructing the backend on content whose first lines contain neither '<!DOCTYPE' nor exactly 'PATN\n' (note: __init__ sniffing requires the exact byte match), then calling convert() — e.g. a generic XML file routed to the USPTO backend, or a patent with a BOM/CRLF so the line comparison fails.

Common situations: Files with Windows CRLF line endings making 'PATN\n' comparison miss; BOM before DOCTYPE; wrong InputFormat forced in pipeline options; non-patent XML misclassified.

Related errors

• The 'beautifulsoup4' and 'defusedxml' packages are required
• Could not initialize USPTO backend for file with hash {self.
• Failed to convert doc (hash={self.document_hash}, name={self
• METS GBS backend could not load document {self.document_hash
• Invalid WebVTT document.

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