docling-project/docling · error · SecurityError

Refusing to expand OOXML package exceeding the uncompressed

Error message

Refusing to expand OOXML package exceeding the uncompressed size limit

What it means

Raised as a SecurityError when the running sum of uncompressed member sizes in an OOXML package exceeds _MAX_TOTAL_UNCOMPRESSED_SIZE (2 GiB, docling/backend/msword_backend.py:137). It is the cumulative counterpart of the per-member guard and protects memory during strict-OOXML normalization, which rewrites the archive into a BytesIO buffer.

Source

Thrown at docling/backend/msword_backend.py:227

    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)
    return normalized


class MsWordDocumentBackend(DeclarativeDocumentBackend):
    """Backend for parsing Word documents (DOCX and DOC files).

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Identify the largest members with unzip -v file.docx and compress/downsample embedded media before conversion.
2. Extract media with a tool (e.g. docx2txt or unzip) and re-zip without unused parts if the package is bloated.
3. For trusted in-house files only, raise _MAX_TOTAL_UNCOMPRESSED_SIZE and reinstall docling from source.
4. Catch SecurityError at the batch level and skip/quarantine the offending document.

Example fix

# before
res = document_converter.convert('huge_report.docx')

# after
from docling.exceptions import SecurityError
try:
    res = document_converter.convert('huge_report.docx')
except SecurityError:
    res = convert_offline('huge_report.docx')  # pre-cleaned copy with downscaled images

import zipfile
TOTAL_LIMIT = 2 * 1024 * 1024 * 1024
with zipfile.ZipFile(path) as z:
    total = sum(i.file_size for i in z.infolist())
if total > TOTAL_LIMIT:
    raise ValueError(f'package inflates to {total} bytes; compress embedded media first')

from docling.exceptions import SecurityError
try:
    result = converter.convert(path)
except SecurityError:
    result = convert_with_downsampled_media(path)

When it happens

Trigger: Loading a .docx where sum(info.file_size for all members) > 2 GiB. Each member individually passes the 512 MiB check but together they exceed the total budget; common with many large embedded images or fonts.

Common situations: Marketing/report docx files stuffed with full-resolution photos, scanned-image documents saved as docx, or malicious archives engineered to exhaust memory during normalization.

Related errors

• Refusing to expand oversized OOXML part: {info.filename}
• Libreoffice not found
• LibreOffice is required to convert a .{source_suffix} file t
• LibreOffice did not produce the expected output: {converted_
• Archive exceeds maximum member count limit of {self.options.

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