docling-project/docling · error · SecurityError

Refusing to expand oversized OOXML part: {info.filename}

Error message

Refusing to expand oversized OOXML part: {info.filename}

What it means

Raised as a SecurityError while normalizing an OOXML package (docx) when a single ZIP member declares an uncompressed size above _MAX_MEMBER_UNCOMPRESSED_SIZE (512 MiB, docling/backend/msword_backend.py:134). This is a zip-bomb guard applied before archive.read() ever decompresses the member. The error is raised during document loading, before any conversion starts.

Source

Thrown at docling/backend/msword_backend.py:222

def _normalize_strict_ooxml(archive: zipfile.ZipFile) -> BytesIO:
    """Rewrite an open Strict OOXML package to Transitional namespaces in memory.

    Only XML/relationship parts that actually carry a Strict namespace are
    decoded and rewritten; every other member (images, fonts, ...) is copied
    through with its original compression, avoiding a needless decode pass. Each
    member is decompressed exactly once. The archive is validated against
    zip-slip and zip-bomb attacks while it is read.
    """
    normalized = BytesIO()
    total_uncompressed = 0
    with zipfile.ZipFile(normalized, "w", zipfile.ZIP_DEFLATED) as target:
        for info in archive.infolist():
            if not _is_safe_zip_member(info.filename):
                raise SecurityError(f"ZIP slip attempt: {info.filename}")
            if info.file_size > _MAX_MEMBER_UNCOMPRESSED_SIZE:
                raise SecurityError(
                    f"Refusing to expand oversized OOXML part: {info.filename}"
                )
            total_uncompressed += info.file_size
            if total_uncompressed > _MAX_TOTAL_UNCOMPRESSED_SIZE:
                raise SecurityError(
                    "Refusing to expand OOXML package exceeding the uncompressed size limit"
                )
            content = archive.read(info.filename)
            if (
                info.filename.endswith((".xml", ".rels"))
                and _STRICT_OOXML_MARKER in content
            ):
                content = _STRICT_OOXML_NS_RE.sub(
                    lambda match: _strict_ns_to_transitional(match.group(0)),
                    content.decode("utf-8"),
                ).encode("utf-8")
            target.writestr(info, content)
    normalized.seek(0)

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Inspect the file: unzip -l file.docx to find which member exceeds 512 MiB and remove or downsample it (e.g. compress embedded media).
2. If the file is trusted and genuinely needs a >512 MiB part, raise _MAX_MEMBER_UNCOMPRESSED_SIZE in your fork/checkout and reinstall docling from source.
3. If the ZIP metadata is corrupt, re-save the document from Word/LibreOffice and retry.
4. Catch SecurityError and route the document to a quarantine/reject path instead of retrying it.

Example fix

# before
convert_document(Path('bomb.docx'))  # SecurityError: oversized OOXML part

# after
from docling.exceptions import SecurityError
try:
    result = convert_document(Path('bomb.docx'))
except SecurityError as e:
    logger.warning('rejected malicious/oversized docx: %s', e)
    result = None

import zipfile
MEMBER_LIMIT = 512 * 1024 * 1024
with zipfile.ZipFile(path) as z:
    oversized = [i.filename for i in z.infolist() if i.file_size > MEMBER_LIMIT]
if oversized:
    raise ValueError(f'oversized members: {oversized}')

from docling.exceptions import SecurityError
try:
    result = converter.convert(path)
except SecurityError as e:
    logger.warning('rejected docx (zip-bomb guard): %s', e)
    result = None

When it happens

Trigger: Passing a .docx file whose ZIP entry (typically a huge media part or document.xml) has info.file_size > 512 MiB; the check runs in _normalize_strict_ooxml during MsWordDocumentBackend.load_msword_file. Corrupted ZIP headers with bogus file_size values trigger it too.

Common situations: Processing archives packed with maximally-compressed padding (zip bombs), documents with embedded multi-hundred-MB videos/images, or a truncated/repaired docx with corrupt central-directory metadata.

Related errors

• Refusing to expand OOXML package exceeding the uncompressed
• ZIP slip attempt: {info.filename}
• 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/74199db9d7cb37ee. Report an issue: GitHub.