docling-project/docling · error · DocumentLoadError

MsWordDocumentBackend could not load document with hash {doc

Error message

MsWordDocumentBackend could not load document with hash {document_hash}

What it means

DocumentLoadError raised by MsWordDocumentBackend.load_msword_file when python-docx's Document() constructor throws for either a Path or BytesIO input. It wraps any unexpected exception (chained via `from e`) so callers get a docling-native error; SecurityError (zip-slip/bomb) is deliberately re-raised unwrapped.

Source

Thrown at docling/backend/msword_backend.py:549

    ) -> DocxDocument:
        try:
            if isinstance(path_or_stream, Path):
                with zipfile.ZipFile(path_or_stream) as archive:
                    if _is_strict_ooxml(archive):
                        return Document(_normalize_strict_ooxml(archive))
                return Document(str(path_or_stream))
            elif isinstance(path_or_stream, BytesIO):
                with zipfile.ZipFile(path_or_stream) as archive:
                    if _is_strict_ooxml(archive):
                        return Document(_normalize_strict_ooxml(archive))
                path_or_stream.seek(0)
                return Document(path_or_stream)
            else:
                return None
        except SecurityError:
            raise
        except Exception as e:
            raise DocumentLoadError(
                f"MsWordDocumentBackend could not load document with hash {document_hash}"
            ) from e

    def _update_history(
        self,
        name: str,
        level: int | None,
        numid: int | None,
        ilevel: int | None,
    ):
        self.history["names"].append(name)
        self.history["levels"].append(level)

        self.history["numids"].append(numid)
        self.history["indents"].append(ilevel)

    def _prev_name(self) -> str | None:
        return self.history["names"][-1]

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Confirm the file opens in Word/LibreOffice; if it is password protected, decrypt it first (python-docx cannot open encrypted docx).
2. If the file is RTF/HTML/legacy .doc, convert it to .docx before passing it to docling.
3. Re-download or re-transfer truncated files (compare size/hash with the source).
4. Catch DocumentLoadError and log document_hash to correlate the failure with the ingest record.

Example fix

# before
result = converter.convert(Path('report.docx'))  # DocumentLoadError

# after
from docling.exceptions import DocumentLoadError
try:
    result = converter.convert(Path('report.docx'))
except DocumentLoadError as e:
    logger.error('failed to load %s (hash=%s)', path, e)
    result = None

import zipfile
try:
    with zipfile.ZipFile(path) as z:
        assert 'word/document.xml' in z.namelist()
except zipfile.BadZipFile:
    raise ValueError('not a valid docx package')

from docling.exceptions import DocumentLoadError
try:
    result = converter.convert(path)
except DocumentLoadError as e:
    logger.error('load failed for %s: %s (cause: %s)', path, e, e.__cause__)

When it happens

Trigger: Loading a corrupt, encrypted/password-protected, or non-ZIP docx: zipfile or docx raises inside Document(...), the except Exception block converts it to DocumentLoadError with the document hash in the message.

Common situations: Password-protected Word files from DMS exports, files truncated mid-upload, HTML or RTF renamed to .docx.

Related errors

• OpenDocument backend could not load document with hash {docu
• docling-parse could not load document {self.document_hash}:
• Libreoffice not found
• LibreOffice is required to convert a .{source_suffix} file t
• LibreOffice did not produce the expected output: {converted_

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